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Chapter 1 


LiMo GTK+ 2.10.1 API 


1.1 References 


[1] High Level Requirements, Version 1.0 Revision 1.5, LiMo Foundation, 22 October 2007 
[2] Software Architecture Document, Version 1.1 Revision 1.4, LiMo Foundation, 11 September 2007 
[3] "GTK+ The GIMP Toolkit", http: //www.gtk.org/ 


1.2 Overview 


The LiMo UI framework GTK is responsible for defining the look and feel of the user interface. This 
provides the model for applications to draw and to handle user events like key events. UI Widgets are the 
package programs to provide the graphical user interface. Applications construct their display with the 
UI Widgets. Input Framework provides applications with the functionality to input text in the handset’s 
current language. 


2 LiMo GTK+ 2.10.1 API 


LiMo GTK Applications 


GTK+ 2.10.1 


Window Manager 


Linux Kernel | FrameBuffer | Input Drivers 


[| Enhanced Open Source Module NN] Plug-in Module 
EJ] Unmodified Open Source Module [ ] Window Manager 


C |] Kernel Level Module 


Figure 1.1: Layered View of the Application UI Framework 


1.2.1 GTK 


Gtk is a toolkit for creating graphical user interfaces. Opensource GTK version 2.10.1 is used as a base 
version. Standard GTK widgets are enhanced for Mobile environment. New set of GTK Widgets useful 
for Mobile Phone application development also included. 


1.2.2 GDK 


GDK is a library acting as wrapper around the low-level drawing and windowing functions provided by the 
underlying windowing system. X11 (TinyX) is used as a Windowing system. 


1.2.3 Pango 


Pango is a library for layout and rendering text with an emphasis on internationalization, rendering is done 
with cairo with client side fonts from fontconfig. 
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1.2.4 Cairo 


Cairo is a 2D graphics library with multiple output device support and operations include stroking, filling 
cubic splines, transforming and compositing translucent images, and anti-aliased text rendering with all 
operations transformable by any affine transformation. 


1.2.5 GLib 


GLib is a low level core library, and provides data structure handling for C, portability wrappers, and 
interfaces for runtime functionality as an event loop, threads, dynamic loading and object system. 


1.3 Industry Standard 


None 


1.4 External API Documents 


None 


1.5 Plug-in Extension Point Interface 


1.5.1 gtkmodules 


Defines Interface for dynamically loadable GTK Modules. 


1.5.2 gtkimmodule 


Defines Interface for dynamically loadable GTK IM Modules. 


1.5.3 gtkimcontext 


Defines Interface for dynamically loadable GTK IM Context. 


1.6 Other Interfaces 


None 


1.7 Other Notes 


None 
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Chapter 2 


Module Index 


2.1 Modules 


Here is a list of all modules: 


GTRECOTE- dao a O64 A A A ea e a ae RS 17 
GKM am 2200 E S ye RA & OO A a AA A A A A EAS 19 
Gtk Themes? ¿cier bs di ae bee 33 
GIRE 6c oe ee Se ecko tee gS. a a al da e 35 
GIKSetuneS 3.44 edo a Bets & HRs Sd be ee GS Gabe ee hae wad 48 
GIKSIVIG Bidet os gate ba dee RE eee ee ba ee Bc Pee Se RA 54 
WSN ewe eae RE ORES hee BREESE RPE OER HE Re wee ELE RS T2 
GtklconFactorY. « s eak mernis RR ERS a e S RER 73 
GtkIconTheme . . o.oo ee 89 
GIKMOdUlE: i gi cr do e G4 e 4 hee eee ae A 102 
GtkChipboatd AA 104 

Standard Gtk Widgets 6.4 26 es ¢ 4-6-5 See BR aa as 119 
Abstract Base Classes ........ ee 120 

Gik Bini. A A RN 121 
E A E EE: 122 
GtkContainer 2... ee 128 
Gikltem: epa EA Ae A A A A RE eS 143 
GHEVASE a eee ag ves tes eds Bek ieee ee Re See ee S WE Ree ee i EON 145 
GtkScale a a be eR EE ee be OER ES Se e ES OS © OO EMS 148 
GtkScrollBat” mdd Boge ute eek in Godete a dy pec beats 132 
GIKRANSe aria O rd a A dan dd ee 133 
GtkWidgët ze roire pegau ee Ee OES a a Deo 159 
Windows , be. & ye ee ss B Bens ani G a a a y a e A a i ada we we & et 210 
GtkDialóg recoit gika ka a aeda hae e por e a We wee F a e e R 211 
E A AN 223 
Display Widgets cion adi ti ds tb a bd a se ads 263 
Gtia: ii rn Bod done ee dd ele pr Rg kde ada 264 
GtkLabell coito de ra a a a a Se 277 
GtkProgressBar: cease ae ee eS A ee ORE ee ee a eS 301 
Buttons and Toggles... o so co ee 308 
GtkButton:«. «2. oc Sow ae Bh Ew OS Se a a a et oe aS 309 


GtkCheckButton . 2... ee 318 


Module Index 


GtkRadioButton . oos pe e ee 321 
GtkToreleButton:. 3.055 ewe be oe ee eee Sates Paw eee kee Ba ee 326 
Numeric / Text Data Entry 2.6.46 05 esse ss e ee Sem ae R 331 
GKE 2. aea ea 4k a wee eae Sh eo he ee a eh E 332 
GtkEntryCompletion . .. ooa e 345 
GtkHS Cale. gA n ta a A A E a ee nde de 354 
Gtk VScale o... ce ke ew we 356 
GtkEditable ovina e GR oe wed BG Mec el ee ob a eb oe we 358 
Multiline Text Editor... 364 
GTM peta e tt ee cae eel Eo: eee oe Dn a Be ee e ee Ree a 365 
GtkTextMark s ow em ee ee 398 
GiIkTextBitther:: 2-404) boscs te Wenge kt Bang ee a ado Bos eb Sa ae 401 
GKEa E siii de A theta teh bee babe te he Ses 427 
GtkTextTag Table. ae rr ee RR EO ee ED ee Ee RO eS 431 
GtkTextVieW <a HR A we HE Swe BO we we we SR 434 
Tree, List and Icon Grid Widgets ........ o... ...... ee 462 
GtkTreeModel o eros i enaa e e eR R ORE a 464 
Gtk THeESelecti OM vs spe a a ee nea E a Ge BOS ee 486 
GtkTreeViewColumn ... 1... ee 494 
GTi. 514 
GtkCellVieWs. cicle ida daba 46 4446404 5 2164 55% 592 
GtkIconView . ooa a 556 
GtkTreeSortable s oiy eaa e a ee eR A ok e a da ds 576 
GtkTreeModelSort ...... ee 579 
GtkTreeModelFilter. 2... ee 584 
GtkCellLayout ec ob eee SSA o8 ow te RSG eRe SHAS BSS ee 590 
GtkCellRenderer ito dr aK Ee Bes ee ws ROE a ati aR Ee 595 
GtkCellEditable: «3.3... costra a a a a 601 
GtkCellRendererPixbuf : s opos duguessa prdu ee 603 
GtkCellRendererProgress .............. e... 606 
GtkCellRendererText . 2... ee 607 
GtkCellRendererToggle .. 2... ee 610 
GtkListStore. s es e soe e a a ee 613 
Gtk TreeStOre: 6.6 48 4b ee ck a Ae A eS E a ck he ic 623 
Menus, Combo Box, Toolbar... 2... 0... ee 633 
GIKIMIENU. Sneed ovate der a Boe ee SS ee Se we a EANA 634 
GtkMenultem oa wese. a Ok BS wd A ce Sd vs aD 641 
GtkMenuShell ms Yin Be eo Be ee a SOA RRE ey Bo ee E 647 
GtkCheckMenultem. . 2... ee 652 
GtkRadioMenultem .. 2... 2. ee 657 
GtkComboBOX escisión 661 
Layout: Containers s escurre E RR 673 
GtkAspectEraMe. 4 enee e e e ee 674 
GtkAhignment: autre a a E ale a da a 676 
GtkHBOX ae o e A aE E a eS A S 679 
GtKVBOX .202:ic<...ooosnssss ra a a ee A 681 
GikPixed: ocur iaa da a 53644 464445 2164 504 683 
GtkLayout,.« eae koe a Se hb Sas bs Sb SRG SES ERA DLE Se eS 686 
GtkNoteBook ....... a 690 
Gtk Tables: 0 ia eGo we se Be Be: A eek Se be eG ew ee Sd 711 
SCTOWING vom E o e Rd seba 718 
GtkHScrollBar- oi. msi. a ee 719 
GtkVSerollBat: 20.66 6 eS a ad a a BOR A 721 
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GtkScrolledWindow . . . . ooo a 723 
Ornmaments << 6 ess cocina cn a a a a EN T31 
Gik Frame: +62 da oa ido Sawer de da D E bis T32 
Miscellaneous Widgets ........... e a e E a e a e a E a a EA 736 
GtkAdjüstment ouch ss rs RE es ke ee ea ES RR 137 
GtkDrawingArea ....... resso rta Ete etan eaa E 741 
GtkEventBox ...... a 743 

Gtk VISWBOTE: s e e 4 da Ss dd ee da aL de a e eL 746 
Custom LiMo GTK Widgets ........... a 749 
GtkColorChooser .. ar seee sr eneee ee 750 
GtkFocusBin 2... eos ea cka ae a e R E a a a a a a a p e O a e 760 
Gtk FORM. a a k a e a e ct an wae beds eh a ee ee a Se i e ee IES: i 765 
GtkFormattedEntry o-se s so ce e mope eka sa e e Be ee a 710 
Gtkindicatóf se o ea a A Ee ees AA A A e we ee 779 
GtkMainWindow .. see aueta ee 784 
GikMeéssageDDialog s c osc es ie e ee ee ee EA we ee 793 
GikSimpleList: 2a Re eee kbd bk soe BEE CREE EE A eed 797 
GikSoftkeyBat® omita e & BOR e a ROR Se ee e BER 804 
GIKS PIN: < e iia a a GE Ee Cen ba Ee eae DE EES BS 809 
GtkSymbollDialog -sie er wok e eee wa he Re ee a ak ee aa 815 
Gdk Window: a aise ean e a E we ae ww a a So wae a aw 818 
GdkE Vents: 4s, ra e ah e Se ele a Beal chs Gey Sed. a Gh eda Se i SA a Se A 819 
Input Method. seo cemas oS ee EE OEE e ee ee ae ee es 820 
GtkIMModule ... 2... ee 821 
GtkIMContext. 3.2 ieee a bo ae SA Sot EES EB a ee BS ab bees 823 
GtkIMMultiContext. 2... ee 832 
GtkIMContextMultitab 2... ee 835 
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Data Structure Index 


3.1 Data Structures 


Here are the data structures with brief descriptions: 


_GdkEventCaseMovement (GDK Case movement event Structure). ............... 
_GtkAdjustment (GtkAdjustment instance stucture). 2... o... o... o... . e... .. . +. 
_GtkAdjustmentClass (GtkAdjustment instance class stucture) ........o o... ooo... 
_GtkAlignment (GtkAlignment interface structure) ........... o... . e... . +... 
_GtkAlignmentClass (GtkAlignment interface class structure) ........... o... ... 
_GtkAspectFrame (GtkAspectFrame instance structure) ...... o... o... .... ... 
_GtkAspectFrameClass (GtkAspectFrame instance class structure ). o... o... ... 
_GtkBin (GtkBin instance structure)... 2... ee 
_GtkBinClass (GtkBin instance class structure)... 2... ee ee ee es 
_GtkBindingSet (GtkBindingSet instance structure)... 2... 2... o... e... . . ... 
_GtkBox (GtkBox instance structure) . . . 2... ee 
_GtkBoxClass (GtkBox instance class structure) ............... ee ee es 
_GtkButton (GtkButton interface structure) ............. e... 
_GtkButtonClass (GtkButton interface class structure) ............. .... . . eee 
_GtkCellLayoutlface (GtkCellLayout interface structure ) . ....... oo... ..... +... 
_GtkCellRenderer (GtkCellRenderer instance structure) ............. . +... . +. . 
_GtkCellRendererAccel (GtkCellRendererAccel instance structure) ............... 
_GtkCellRendererClass (GTK Native GtkCellRenderer instance class structure ) . ........ 
_GtkCellRendererPixbuf (GtkCellRendererPixbuf instance structure) .............. 
_GtkCellRendererPixbufClass (GTK Native GtkCellRendererPixbuf instance class structure ) . . 
_GtkCellRendererProgress (GtkCellRendererProgress instance structure) ............ 
_GtkCellRendererProgressClass (GtkCellRendererProgress instance class structure) ...... 
_GtkCellRendererText (GtkCellRendererText instance structure). ................ 
_GtkCellRendererTextClass (GTK Native GtkCellRendererText instance class structure) . . ... 
_GtkCellRendererToggle (GtkCellRendererToggle instance structure) .............. 
_GtkCellRendererToggleClass (GtkCellRendererToggle instance class structure) ........ 
_GtkCellView (GtkCellView instance structure)... 2... e o e ee e... 
_GtkCellViewClass (GtkCellView instance class structure ) . ............... .. . .. 
_GtkCheckButton (GtkCheckButton interface structure) .............. .. . . . . .. 
_GtkCheckButtonClass (GtkCheckButton interface class structure) ............... 
_GtkCheckMenultem (GtkCheckMenultem instance Structure). .............. ... 
_GtkCheckMenultemClass (GTK Native GtkCheckMenultem instance class structure) ..... 
_GtkColorChooser (GtkColorChooser instance structure)... 2... 2.2.2... 0020. eee 
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_GtkColorChooserClass (GtkColorChooserClass instance structure) ............... 873 
_GtkComboBox (GtkComboBox instance structure) ...........0 0.002 . . .. 874 
_GtkComboBoxClass (GtkComboBox instance calss structure) ................. 875 
_GtkContainer (GtkContainer instance structure) ............... e... 876 
_GtkContainerClass (GtkContainer instance class structure) ................... 877 
_GtkDialog (GtkDialog instance structure) ........ o... e... e... e... 878 
_GtkDialogClass (GtkDialogClass class) .. 2... 2.2.2.2... 0.000000 . e... . +... 879 
_GtkDrawingArea (GtkDrawingArea instance structure) ........ o... e... . .. +... 880 
_GtkDrawingAreaClass (GtkDrawingArea instance class structure) ............... 881 
_GtkEditableClass (GtkEditable instance class structure) ........... o... .. . .. .. .. 882 
_GtkEntry (GtkEntry instance structure ) ......... o... e... e... 884 
_GtkEntryClass (GTK Native GtkEntry instance class structure) ................. 886 
_GtkEntryCompletion (GtkEntryCompletion instance structure) ........ o... o... 888 
_GtkEntryCompletionClass (GtkEntryCompletion instance class structure) ........... 889 
_GtkEventBox (GtkEventBox instance structure ) .............. e... 891 
_GtkEventBoxClass (GtkEventBox instance class structure) ................ . .. 892 
_GtkFixed (GtkFixed instance structure)... . o.o e o ee es 893 
_GtkFixedClass (GtkFixed instance class structure)... 2... 2. ee ee ee es 894 
_GtkFocusBin (GtkFocusBin instance structure) ............. e... 895 
_GtkFocusBinClass (GtkFocusBinClass instance structure)... .........-020 00005 896 
_GtkForm (GtkForm represents a scene of GUI application) ................0.. 897 
_GtkFormattedEntry (GtkFormattedEntry instance structure ) . ....... o... o... ... 898 
_GtkFormattedEntryClass (GtkFormattedEntry instance class structure) ............. 899 
_GtkFormClass (GtkForm Class) .......... ee 901 
_GtkFrame (GtkFrame instance structure ) ........ e... 902 
_GtkFrameClass (GtkFrame instance class structure ) .................. +... . 903 
_GtkHBox (GtkHBox instance structure) ........ es 904 
_GtkHBoxClass (GtkHBox instance class structure) ............. .. .. ee eee 905 
_GtkHScale (GtkHScale instance structure) ............ ee es 906 
_GtkHScaleClass (GtkHScale instance class structure) . . . . o. ooo 20200000 907 
_GtkHScrollbar (GtkHScrollbar instance structure) .. 2... 2. ee 908 
_GtkHScrollbarClass (GtkHScrollbar instance class structure) ..............0065 909 
_GtkIconFactory (GtkIconFactory instance structure)... 2... 2... o... e... .. . .. 910 
_GtkIconFactoryClass (GtkIconFactory instance class structure) ........ o... o... .. 911 
_GtkIconTheme (GtkIconTheme instance structure) ............ 0.000200 eee 912 
_GtkIconThemeClass (GtkIconTheme instance class structure)... ...........2005 913 
_GtkIconView (GtkIconView instance structure) ............. e... 914 
_GtkIconViewClass (GtkIconView instance class structure) ............2-000005 915 
_GtkImage (GtkImage instance structure ) . . . 2... ee, 916 
_GtkImageAnimationData (GtkImageAnimationData instance structure) ............ 917 
_GtkImageClass (GtkImage instance class structure) ....... o... oo... .... ... 918 
_GtkImagelconNameData (GtkImagelconNameData instance Structure) ............. 919 
_GtkImagelconSetData (GtkImagelconSetData instance structure ) . ........ o... .. 920 
_GtkImagelmageData (GtkImageImageData instance structure) ........ o... oo... 921 
_GtkImagePixbufData (GtkImagePixbufData instance structure) ..... o... o... ... 9722 
_GtkImagePixmapData (GtkImagePixmapData instance structure) ........ o... ... 923 
_GtkImageStockData (GtkImageStockData instance structure) ....... o... o... ... 924 
_GtkIMContext (GtkIMContext instance structure)... 2... 2... .. 2.000002 eee eee 925 
_GtkIMContextClass (GtkIMContext instance class structure) ..............2005 926 
_GtkIMContextMultitab (GtkIMContextMultitab instance structure). .............. 927 
_GtkIMContextMultitabClass (GtkIMContextMultitab instance class structure) ......... 928 
_GtkIMMulticontext (GtkIMMulticontext instance structure). ..............0005 929 
_GtkIMMulticontextClass (GtkIMMulticontext instance class structure) ............. 930 
_GtkIndicator (GtkIndicator instance structure) .............. ee ee 931 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


3.1 Data Structures 11 


_GtkIndicatorClass (GtkIndicator instance class structure) .................. . .. 932 
_Gtkltem (GtkItem instance structure)... 2... ee 933 
_GtkltemClass (GtkItem instance class structure ) ............... ee ee 934 
_GtkLabel (GtkLabel instance structure)... . o.o e o ee ee 935 
_GtkLabelClass (GTK Native GtkLabel instance class structure) ................. 936 
_GtkLayout (GtkLayout instance structure) ........ o... . +... e... 937 
_GtkLayoutClass (GtkLayout instance class structure) ........ o... . o... ... ... 938 
_GtkListStore (GtkListStore instance structure ) ................ e... 939 
_GtkListStoreClass (GtkListStore instance class structure) ........ o... ... .. . .. 940 
_GtkMain Window (GtkMainWindow is the toplevel frame window which can contain other wid- 

PCS ete foie ke ot ete e Bene cee Soo p Sa PO ee Be eid 941 
_GtkMainWindowClass (GtkMainWindow Class)... ....... 002 eee ee ee es 943 
_GtkMenu (GtkMenu instance structure) 2... 2... 2 ee es 944 
_GtkMenuClass (GTK Native GtkMenu instance class structure)... ............-. 945 
_GtkMenultem (GtkMenultem instance structure) ............0 00002 eens 946 
_GtkMenultemClass (GTK Native GtkMenultem instance class structure) ............ 947 
_GtkMenuShell (GtkMenuShell instance structure)... 2... 0... 2 ee ee es 948 
_GtkMenuShellClass (GTK Native GtkMenuShell instance class structure) ........... 949 
_GtkMessageBox (GtkMessageBox class)... ooa eee 950 
_GtkMessageBoxClass (MessageBoxClass Class)... o... o... a 951 
_GtkMessageDialog (GtkMessageDialog instance structure) ...... o... ooo... o... 952 
_GtkMessageDialogClass (GtkMessageDialog instance class structure) ............. 9353 
_GtkMisc (GtkMisc interface structure) ......... a ee es 954 
_GtkMiscClass (GtkMisc interface class structure) .............. .. . +... . +. 953 
_GtkNotebook (GtkNotebook instance structure) ............... o... 956 
_GtkNotebookClass (GtkNotebook instance class structure) .................... 957 
_GtkObject (GtkObject instance class structure). . . . o.oo o... . o... . e... . . . +. 958 
_GtkObjectClass (GtkObject instance class structure ) o... o... oo... .... ... 959 
_GtkProgress (GtkProgress StUCture).............. o... 960 
_GtkProgressBar (GtkProgressBar instance stucture) ......... o... o... e... . .. . +... 961 
_GtkProgressBarClass (GtkProgressBar instance Class structure) ................ 962 
_GtkProgressClass (GtkProgress class stucture ) . ..... o... o... a 963 
_GtkRadioButton (GtkRadioButton interface StrUCtUTE) . .............. +... . . .. 964 
_GtkRadioButtonClass (GtkRadioButton interface class structure) ................ 965 
_GtkRadioMenultem (GtkRadioMenultem instance structure) ............... . .. 966 
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Module Documentation 


6.1 GTK+ Core 


Modules 


e GtkMain 


This provides basic GTK functionalities like Initialize, event delivery loop, destroy etc. 


+ GtkThemes 


Themes generally live in either a public directory (available to all users, typically in /usr/share/themes/) or 
in ~/.themes/ (just for you). 


e GtkRe 


GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ pro- 
gram at runtime. 


e GtkSettings 


This file implements the Sharing settings between applications. 


e GtkStyle 
This GtkStyle widget provide Functions for drawing widget parts. 


e I18N 


Provides il8n conversion APIs. 


e GtkIconFactory 


An icon factory manages a collection of GtkIconSet; a GtkIconSet manages a set of variants of a particular 
icon (i.e. 


¢ GtkIconTheme 


GtkIconTheme provides a facility for looking up icons by name and size. 


e GtkModule 
This file defines the functions of GtkModule. 


e GtkClipboard 
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The GtkClipboard object represents a clipboard of data shared between different processes or between 
different widgets in the same process. 
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6.2 GtkMain 


6.2.1 Detailed Description 


This provides basic GTK functionalities like Initialize, event delivery loop, destroy etc. 


Before using GTK+, you need to initialize it; initialization connects to the window system display, and 
parses some standard command line arguments. The gtk_init() function initializes GTK+. gtk_init() exits 
the application if errors occur; to avoid this, use gtk_init_check(). gtk_init_check() allows you to recover 
from a failed GTK+ initialization - you might start up your application in text mode instead. 


Like all GUI toolkits, GTK+ uses an event-driven programming model. When the user is doing nothing, 
GTK+ sits in the main loop and waits for input. If the user performs some action - say, a key press - then the 
main loop "wakes up" and delivers an event to GTK+. GTK+ forwards the event to one or more widgets. 


When widgets receive an event, they frequently emit one or more signals. Signals notify your program that 
"something interesting happened" by invoking functions you’ve connected to the signal with g_signal_- 
connect(). Functions connected to a signal are often termed callbacks. 


When your callbacks are invoked, you would typically take some action - for example, when an Open 
button is clicked you might display a GtkFileSelectionDialog. After a callback finishes, GTK+ will return 
to the main loop and await more user input. 


Code Example: 

int 

main (int argc, char x*xargv) 
{ 

// Initialize il8n support 


gtk_set_locale (); 


// Initialize the widget set 
gtk_init (&argc, &argv); 


// Create the main window 
mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL) ; 


// Set up our GUI elements 
// Show the application window 
gtk_widget_show_all (mainwin) ; 


// Enter the main event loop, and wait for user interaction 
gtk_main (); 


// The user lost interest 
return 0; 


} 


It’s OK to use the GLib main loop directly instead of gtk_main(), though it involves slightly more typing. 


Typedefs 


e typedef gint(* GtkKeySnoopFunc )(Gtk Widget *grab_widget, GdkEventKey «event, gpointer func_- 
data) 


Key snooper functions are called before normal event delivery. 


e typedef void(« CMEventHandler )(GdkEventCaseMovement xevent) 
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Case Movement Event handler function will be called on any Mobile case movement event. 


e typedef gboolean(* AppQuitState Handler )(GdkEvent xevent) 


AppQuitStateHandler will be called by GTK before generating application window delete event to check 
whether the application can close. 


Functions 


e gboolean gtk_parse_args (int x*argc, char ***argv) 


Parses command line arguments, and initializes global attributes of GTK+, but does not actually open a 
connection to a display. 


e void gtk_init (int argc, char ***argv) 


Call this function before using any other GTK+ functions in your GUI applications. 


e gboolean gtk_init_check (int *argc, char x*xargv) 


This function does the same work as gtk_init() with only a single change: It does not terminate the program 
if the GUI can’t be initialized. 


e gboolean gtk _init_with_args (int *argc, char ***argv, char *parameter_string, GOptionEntry 
xentries, char *translation_domain, GError *xerror) 


This function does the same work as gtk_init_check(). 


e GOptionGroup x gtk_get_option_group (gboolean open_default_display) 
Returns a GOptionGroup for the commandline arguments recognized by GTK+ and GDK. 


e void gtk_disable_setlocale (void) 


Prevents gtk_init(), gtk_init_check(), gtk_init_with_args() and gtk_parse_args() from automatically calling 
setlocale (LC_ALL, ""). 


e gchar * gtk_set_locale (void) 


Initializes internationalization support for GTK+. 


e PangoLanguage * gtk_get_default_language (void) 


Returns the PangoLanguage for the default language currently in effect. 


e gboolean gtk_events_pending (void) 


Checks if any events are pending. 


e void gtk_main_do_event (GdkEvent xevent) 


Processes a single GDK event. 


e void gtk_main (void) 


Runs the main loop until gtk_main_quit() is called. 


e guint gtk_main_level (void) 


Asks for the current nesting level of the main loop. 


e void gtk_main_quit (void) 
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Makes the innermost invocation of the main loop return when it regains control. 


e gboolean gtk_main_iteration (void) 


Runs a single iteration of the mainloop. 


e gboolean gtk_main_iteration_do (gboolean blocking) 


Runs a single iteration of the mainloop. 


e gboolean gtk_true (void) G_LGNUC_CONST 


All this function does it to return TRUE. 


e gboolean gtk_false (void) G_LGNUC_CONST 
Analogical to gtk_true() this function does nothing but always returns FALSE. 


e void gtk_grab_add (GtkWidget «widget) 
Makes widget the current grabbed widget. 


e GtkWidget * gtk_grab_get_current (void) 


Queries the current grab of the default window group. 


e void gtk_grab_remove (GtkWidget «widget) 


Removes the grab from the given widget. 


e void gtk_init_add (GtkFunction function, gpointer data) 


Registers a function to be called when the mainloop is started. 


e void gtk_quit_add_destroy (guint main_level, GtkObject *object) 


Trigger destruction of object in case the mainloop at level main_level is quit. 


e guint gtk quit_add (guint main_level, GtkFunction function, gpointer data) 


Registers a function to be called when an instance of the mainloop is left. 


e guint gtk_quit_add full (guint main_level, GtkFunction function, GtkCallbackMarshal marshal, 
gpointer data, GtkDestroyNotify destroy) 


Registers a function to be called when an instance of the mainloop is left. 


e void gtk_quit_remove (guint quit_handler_id) 


Removes a quit handler by its identifier. 


e void gtk_quit_remove_by_data (gpointer data) 


Removes a quit handler identified by its data field. 


e guint gtk_key_snooper_install (GtkKeySnoopFunc snooper, gpointer func_data) 


Installs a key snooper function, which will get called on all key events before delivering them normally. 


e void gtk_key_snooper_remove (guint snooper_handler_id) 


Removes the key snooper function with the given id. 


e GdkEvent « gtk_get_current_event (void) 


Obtains a copy of the event currently being processed by GTK+. 
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e guint32 gtk_get_current_event_time (void) 


If there is a current event and it has a timestamp, return that timestamp, otherwise return GDK_CURRENT_- 
TIME. 


e gboolean gtk_get_current_event_state (GdkModifierType «state) 


If there is a current event and it has a state field, place that state field in state and return TRUE, otherwise 
return FALSE. 


e GtkWidget x gtk_get_event_widget (GdkEvent x*event) 


If event is NULL or the event was not associated with any widget, returns NULL, otherwise returns the 
widget that received the event originally. 


e void gtk_main_set_cm_event_handler (CMEventHandler callback) 


Application can use this API to set the handler for Mobile Case Movement event. 


e void gtk_main_set_app_quit_state_validator (AppQuitStateHandler callback) 


Application can use this API to set the Application Quit handler. 


6.2.2 Typedef Documentation 
6.2.2.1 typedef gboolean(« AppQuitStateHandler)(GdkEvent «event) 
AppQuitStateHandler will be called by GTK before generating application window delete event to check 


whether the application can close. 


GTK may generate Window Delete event for the reason of the occurence of the event specified in the 
function’s event parameter ( For Example, case movement event). GTK will invoke AppQuitStateHandler 
before generating Window Delete event. Application can return FALSE, If it is not ready to quit. Based on 
the AppQuitStateHandler return value Window Delete event will be generated by GTK. If AppQuitState- 
Handler is not set by application, by default GTK will generate Window Delete event. 


Parameters: 


event [in] GdkEvent. The Event that triggered GTK to check with application whether it can close. 


Returns: 


TRUE/FALSE. If TRUE, GTK generates Window Delete events to close the application. 


Since 


LIMO R1 


6.2.2.2 typedef void(* CMEventHandler)(GdkEventCaseMovement xevent) 


Case Movement Event handler function will be called on any Mobile case movement event. 


Parameters: 


event [in] GdkEventCaseMovement 
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Since 


LIMO R1 


6.2.2.3 typedef gint(* GtkKeySnoopFunc)(GtkWidget «grab_widget, GdkEventKey «event, 
gpointer func_data) 
Key snooper functions are called before normal event delivery. 


They can be used to implement custom key event handling. 


Parameters: 
grab_widget [in] the widget to which the event will be delivered. 
event [in] the key event. 


func_data [in] the func_data supplied to gtk_key_snooper_install(). 


Returns: 


TRUE to stop further processing of event, FALSE to continue. 


6.2.3 Function Documentation 
6.2.3.1 void gtk_disable_setlocale (void) 


Prevents gtk_init(), gtk_init_check(), gtk_init_with_args() and gtk_parse_args() from automatically calling 
setlocale (LC_ALL, ""). 


You would want to use this function if you wanted to set the locale for your program to something other 
than the user’s locale, or if you wanted to set different values for different locale categories. 


6.2.3.2 gboolean gtk_events_pending (void) 


Checks if any events are pending. 


This can be used to update the GUI and invoke timeouts etc. while doing some time intensive computa- 
tion. 


Returns: 


TRUE if any events are pending, FALSE otherwise. 


Code example: 


//computation going on 


while (gtk_events_pending ()) 
gtk_main_iteration (); 


// computation continued 
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6.2.3.3 gboolean gtk_false (void) 
Analogical to gtk_true() this function does nothing but always returns FALSE. 


Returns: 


FALSE 


6.2.3.4 GdkEventx gtk_get_current_event (void) 


Obtains a copy of the event currently being processed by GTK+. 


For example, if you get a "clicked" signal from GtkButton, the current event will be the GdkEventButton 
that triggered the "clicked" signal. The returned event must be freed with gdk_event_free(). If there is no 
current event, the function returns NULL. 


Returns: 


a copy of the current event, or NULL if no current event. 


6.2.3.5 gboolean gtk_get_current_event_state (GdkModifierType + state) 


If there is a current event and it has a state field, place that state field in state and return TRUE, otherwise 
return FALSE. 


Parameters: 


state [in] a location to store the state of the current event 


Returns: 


TRUE if there was a current event and it had a state field 


6.2.3.6 guint32 gtk_get_current_event_time (void) 


If there is a current event and it has a timestamp, return that timestamp, otherwise return GDK_- 
CURRENT_TIME. 


Returns: 


the timestamp from the current event, or GDK_CURRENT_TIME. 


6.2.3.7 PangoLanguagex gtk_get_default_language (void) 


Returns the PangoLanguage for the default language currently in effect. 


(Note that this can change over the life of an application.) The default language is derived from the current 
locale. It determines, for example, whether GTK+ uses the right-to-left or left-to-right text direction. See 
_gtk_get_lc_ctype() for notes on behaviour on Windows. 


Returns: 


the default language as a PangoLanguage, must not be freed. 
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6.2.3.8 GtkWidget» gtk_get_event_widget (GdkEvent « event) 


If event is NULL or the event was not associated with any widget, returns NULL, otherwise returns the 
widget that received the event originally. 


Parameters: 


event [in] a GdkEvent 


Returns: 


the widget that originally received event, or NULL 


6.2.3.9 GOptionGroup+* gtk_get_option_group (gboolean open_default_display) 


Returns a GOptionGroup for the commandline arguments recognized by GTK+ and GDK. 


You should add this group to your GOptionContext with g_option_context_add_group(), if you are using 
g_option_context_parse() to parse your commandline arguments. 


Parameters: 


open_default_display [in] whether to open the default display when parsing the commandline argu- 
ments 


Returns: 


a GOptionGroup for the commandline arguments recognized by GTK+ 


6.2.3.10 void gtk_grab_add (Gtk Widget « widget) 


Makes widget the current grabbed widget. 


This means that interaction with other widgets in the same application is blocked and mouse as well as 
keyboard events are delivered to this widget. 


Parameters: 


widget [in] The widget that grabs keyboard and pointer events. 


6.2.3.11 GtkWidget» gtk_grab_get_current (void) 


Queries the current grab of the default window group. 


Returns: 


The widget which currently has the grab or NULL if no grab is active. 
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6.2.3.12 void gtk_grab_remove (GtkWidget « widget) 


Removes the grab from the given widget. 


You have to pair calls to gtk_grab_add() and gtk_grab_remove(). 


Parameters: 


widget [in] The widget which gives up the grab. 


6.2.3.13 void gtk_init (int x argc, char xxx argv) 


Call this function before using any other GTK+ functions in your GUI applications. 


It will initialize everything needed to operate the toolkit and parses some standard command line options. 
argc and argv are adjusted accordingly so your own code will never see those standard arguments. 


Note that there are some alternative ways to initialize GTK+: if you are calling gtk_parse_args(), gtk_- 
init_check(), gtk_init_with_args() or g_option_context_parse() with the option group returned by gtk_- 
get_option_group(), you don’t have to call gtk_init(). 


: This function will terminate your program if it was unable to initialize the GUI for some reason. If you 
want your program to fall back to a textual interface you want to call gtk_init_check() instead. 
Parameters: 


argc [in]: Address of the argc parameter of your main() function. Changed if any arguments were 
handled. 


argv [in] Address of the argv parameter of main(). Any parameters understood by gtk_init() are 
stripped before return. 


6.2.3.14 void gtk_init_add (GtkFunction function, gpointer data) 
Registers a function to be called when the mainloop is started. 


Parameters: 


function [in] Function to invoke when gtk_main() is called next. 


data [in] Data to pass to that function. 


6.2.3.15 gboolean gtk_init_check (int « argc, char xxx argv) 

This function does the same work as gtk_init() with only a single change: It does not terminate the program 
if the GUI can’t be initialized. 

Instead it returns FALSE on failure. 

This way the application can fall back to some other means of communication with the user - for example 
a curses or command line interface. 

Parameters: 


argc [in] Address of the argc parameter of your main() function. Changed if any arguments were 
handled. 
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argv [in] Address of the argv parameter of main(). Any parameters understood by gtk_init() are 
stripped before return. 
Returns: 


TRUE if the GUI has been successfully initialized, FALSE otherwise. 


6.2.3.16 gboolean gtk_init_with_args (int « argc, char xxx argv, char x parameter_string, 
GOptionEntry + entries, char + translation_domain, GError ** error) 

This function does the same work as gtk_init_check(). 

Additionally, it allows you to add your own commandline options, and it automatically generates nicely 

formatted —help output. Note that your program will be terminated after writing out the help output. 

Parameters: 


argc [in] a pointer to the number of command line arguments. 
argv [in] a pointer to the array of command line arguments. 


parameter_string [in] a string which is displayed in the first line of —help output, after programname 
[OPTION...] 


entries [in] a NULL-terminated array of GOptionEntrys describing the options of your program 


translation_domain [in] a translation domain to use for translating the —help output for the options in 
entries with gettext(), or NULL 


— a return location for errors 


Returns: 


TRUE if the GUI has been successfully initialized, FALSE otherwise. 


6.2.3.17 guint gtk_key_snooper_install (GtkKeySnoopFunc snooper, gpointer func_data) 
Installs a key snooper function, which will get called on all key events before delivering them normally. 


Parameters: 


snooper [in] a GtkKeySnoopFunc. 


func_data [in] data to pass to snooper. 


Returns: 


a unique id for this key snooper for use with gtk_key_snooper_remove(). 


6.2.3.18 void gtk_key_snooper_remove (guint snooper_handler_id) 
Removes the key snooper function with the given id. 


Parameters: 


snooper_handler_id [in] Identifies the key snooper to remove. 
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6.2.3.19 void gtk_main (void) 


Runs the main loop until gtk_main_quit() is called. 


You can nest calls to gtk_main(). In that case gtk_main_quit() will make the innermost invocation of the 
main loop return. 


6.2.3.20 void gtk_main_do_event (GdkEvent « event) 


Processes a single GDK event. 


This is public only to allow filtering of events between GDK and GTK+. You will not usually need to call 
this function directly. 


While you should not call this function directly, you might want to know how exactly events are handled. 
So here is what this function does with the event: 


1) Compress enter/leave notify events. If the event passed build an enter/leave pair together with the next 
event (peeked from GDK) both events are thrown away. This is to avoid a backlog of (de-)highlighting 
widgets crossed by the pointer. 


2) Find the widget which got the event. If the widget can’t be determined the event is thrown away unless 
it belongs to a INCR transaction. In that case it is passed to gtk_selection_incr_event(). 


3) Then the event is passed on a stack so you can query the currently handled event with gtk_get_current_- 
event(). 


4) The event is sent to a widget. If a grab is active all events for widgets that are not in the contained in the 
grab widget are sent to the latter with a few exceptions: 


e Deletion and destruction events are still sent to the event widget for obvious reasons. 
e Events which directly relate to the visual representation of the event widget. 


e Leave events are delivered to the event widget if there was an enter event delivered to it before 
without the paired leave event. 


e Drag events are not redirected because it is unclear what the semantics of that would be. 


e Another point of interest might be that all key events are first passed through the key snooper func- 
tions if there are any. Read the description of gtk_key_snooper_install() if you need this feature. 


5) After finishing the delivery the event is popped from the event stack. 


Parameters: 


event [in] An event to process (normally) passed by GDK. 


6.2.3.21 gboolean gtk_main_iteration (void) 


Runs a single iteration of the mainloop. 


If no events are waiting to be processed GTK+ will block until the next event is noticed. If you don’t want 
to block look at gtk_main_iteration_do() or check if any events are pending with gtk_events_pending() 
first. 
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Returns: 


TRUE if gtk_main_quit() has been called for the innermost mainloop. 


6.2.3.22 gboolean gtk_main_iteration_do (gboolean blocking) 


Runs a single iteration of the mainloop. 


If no events are available either return or block dependent on the value of blocking. 


Parameters: 


blocking [in] TRUE if you want GTK+ to block if no events are pending. 


Returns: 


TRUE if gtk_main_quit() has been called for the innermost mainloop. 


6.2.3.23 guint gtk_main_level (void) 


Asks for the current nesting level of the main loop. 


This can be useful when calling gtk_quit_add(). 


Returns: 


the nesting level of the current invocation of the main loop. 


6.2.3.24 void gtk_main_quit (void) 


Makes the innermost invocation of the main loop return when it regains control. 


6.2.3.25 void gtk_main_set_app_quit_state_validator (AppQuitStateHandler callback) 


Application can use this API to set the Application Quit handler. 


GTK may close the application by generating Window delete event on set of events ( Fox Example, on 
Flip Close/Slider Close) AppQuitStateHandler will be called by GTK before generating window delete 
event. Based on the return value of the AppQuitStateHandler, Window delete event will be generated. 
Applications can set AppQuitStateHandler to override the GTK application default quit behavior. 


[VENDOR SPECIFIC BEHAVIOR]: The event set (Reason to close) to generate window delete event is 
vendor specific one. 
Parameters: 


callback [in] AppQuitStateHandler callback 


Returns: 
void 
Since 


LIMO R1 
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6.2.3.26 void gtk_main_set_cm_event_handler (CMEventHandler callback) 


Application can use this API to set the handler for Mobile Case Movement event. 


On any case movement event ( Example: Flip Open / Close, or Slide open/Close), this callback function 
will be invoked. 


Parameters: 

callback [in] CMEventHandler function pointer. 
Returns: 

void 
Since 


LIMO R1 


6.2.3.27 gboolean gtk_parse_args (int « argc, char xxx argv) 


Parses command line arguments, and initializes global attributes of GTK+, but does not actually open a 
connection to a display. 


(See gdk_display_open(), gdk_get_display_arg_name()) 


Any arguments used by GTK+ or GDK are removed from the array and argc and argv are updated accord- 
ingly. 

You shouldn’t call this function explicitely if you are using gtk_init(), or gtk_init_check(). 

Parameters: 


argc [in] a pointer to the number of command line arguments. 


argv [in] a pointer to the array of command line arguments. 


Returns: 


TRUE if initialization succeeded, otherwise FALSE. 


6.2.3.28 guint gtk_quit_add (guint main_level, GtkFunction function, gpointer data) 
Registers a function to be called when an instance of the mainloop is left. 


Parameters: 
main_level [in] Level at which termination the function shall be called. You can pass O here to have 
the function run at the termination of the current mainloop. 


function [in] The function to call. This should return 0 to be removed from the list of quit handlers. 
Otherwise the function might be called again. 


data [in] Pointer to pass when calling function. 


Returns: 


A handle for this quit handler (you need this for gtk_quit_remove()) or 0 if you passed a NULL pointer 
in function. 
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6.2.3.29 void gtk_quit_add_destroy (guint main_level, GtkObject x object) 
Trigger destruction of object in case the mainloop at level main_level is quit. 


Parameters: 


main_level [in] Level of the mainloop which shall trigger the destruction. 


object [in] Object to be destroyed. 


6.2.3.30 guint gtk_quit_add_full (guint main_level, GtkFunction function, GtkCallbackMarshal 
marshal, gpointer data, GtkDestroyNotify destroy) 
Registers a function to be called when an instance of the mainloop is left. 


In comparison to gtk_quit_add() this function adds the possibility to pass a marshaller and a function to be 
called when the quit handler is freed. 


The former can be used to run interpreted code instead of a compiled function while the latter can be used 
to free the information stored in data (while you can do this in function as well)... So this function will 
mostly be used by GTK+ wrappers for languages other than C. 


Parameters: 


main_level [in] Level at which termination the function shall be called. You can pass O here to have 
the function run at the termination of the current mainloop. 


function [in] The function to call. This should return 0 to be removed from the list of quit handlers. 
Otherwise the function might be called again. 


marshal [in] The marshaller to be used. If this is non-NULL, function is ignored. 
data [in] Pointer to pass when calling function. 


destroy [in] Function to call to destruct data. Gets data as argument. 


Returns: 


A handle for this quit handler (you need this for gtk_quit_remove()) or 0 if you passed a NULL pointer 
in function. 


6.2.3.31 void gtk_quit_remove (guint quit_handler_id) 
Removes a quit handler by its identifier. 


Parameters: 


quit_handler_id [in] Identifier for the handler returned when installing it. 


6.2.3.32 void gtk_quit_remove_by_data (gpointer data) 


Removes a quit handler identified by its data field. 


Parameters: 


data [in] The pointer passed as data to gtk_quit_add() or gtk_quit_add_full(). 
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6.2.3.33 gchar gtk_set_locale (void) 


Initializes internationalization support for GTK+. 
gtk_init() automatically does this, so there is typically no point in calling this function. 


If you are calling this function because you changed the locale after GTK+ is was initialized, then calling 
this function may help a bit. (Note, however, that changing the locale after GTK+ is initialized may produce 
inconsistent results and is not really supported.) 


In detail - sets the current locale according to the program environment. This is the same as calling the C 
library function setlocale (LC_ALL, "") but also takes care of the locale specific setup of the windowing 
system used by GDK. 


Returns: 


a string corresponding to the locale set, typically in the form lang COUNTRY, where lang is an ISO- 
639 language code, and COUNTRY is an ISO-3166 country code. On Unix, this form matches the 
result of the setlocale(); it is also used on other machines, such as Windows, where the C library returns 
a different result. The string is owned by GTK+ and should not be modified or freed. 


6.2.3.34 gboolean gtk_true (void) 


All this function does it to return TRUE. 

This can be useful for example if you want to inhibit the deletion of a window. Of course you should not 
do this as the user expects a reaction from clicking the close icon of the window... 

Returns: 


TRUE 
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6.3 GtkThemes 


6.3.1 Detailed Description 


Themes generally live in either a public directory (available to all users, typically in /usr/share/themes/) or 
in ~/.themes/ (just for you). 


A convenient place to put the themes you create are in ~/.themes/YOUR_THEME NAME/stk-2.0/. 
Within this gtk-2.0 directory you will place all files that go with your theme. Note that if themes of 
the same name are installed in both the public and the ~/.themes directories that GNOME will use the one 
in ~/.themes. 


A small example follows, that shows how to create very a basic theme. 


style "default-style" 

{ 

modify the x/ythickness, used for spacing all over the place 
xthickness = 3 

ythickness = 3 


one can set so called "style properties" 
GtkRange::slider-width = 15 


set the background to a light grey 


bg [NORMAL] = "#f6f6f6" 
and the forground to black 
fg [NORMAL] = "#000000" 


class "GtkWidget" style "default-style" All, this snippet does, is create a style called "default-style" which 
then gets applied to all widgets. 
Functions 


e GtkThemeEngine x gtk_theme_engine_ get (const gchar xname) 


Returns the Theme Engine. 


e GtkRcStyle x gtk_theme_engine_create_rc_style (GtkThemeEngine *engine) 


Creates RC from Theme Engine. 


6.3.2 Function Documentation 


6.3.2.1 GtkRcStylex gtk_theme_engine_create_rc_style (GtkThemeEngine x engine) 
Creates RC from Theme Engine. 


Parameters: 


engine [in] GtkThemeEngine 


Returns: 


GtkRcStyle 
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6.3.2.2 GtkThemeEnginex gtk_theme_engine_get (const gchar « name) 
Returns the Theme Engine. 


Parameters: 


name [in] Name of the Theme engine 


Returns: 


GtkThemeEngine 
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6.4 GtkRe 


6.4.1 Detailed Description 


GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ pro- 
gram at runtime. 


Default files 


An application can cause GTK+ to parse a specific RC file by calling gtk_rc_parse(). In addition to 
this, certain files will be read at the end of gtk _init(). Unless modified, the files looked for will be 
<S Y SCONFDIR >/gtk-2.0/gtkrc and .gtkrc-2.0 in the users home directory. (<SYSCONFDIR> defaults 
to /usr/local/etc. It can be changed with the —prefix or —-sysconfdir options when configuring GTK+.) Note 
that although the filenames contain the version number 2.0, all 2.x versions of GTK+ look for these files. 
The set of these default files can be retrieved with gtk_rc_ get_default_files() and modified with gtk_rc_- 
add _default_file() and gtk_rc_set_default_files(). Additionally, the GTK2_RC_FILES environment vari- 
able can be set to a G_SEARCHPATH_SEPARATOR_S-separated list of files in order to overwrite the set 
of default files at runtime. For each RC file, in addition to the file itself, GTK+ will look for a locale- 
specific file that will be parsed after the main file. For instance, if LANG is set to ja_JP.ujis, when loading 
the default file ~/.gtkre then GTK+ looks for —/.gtkrc.ja_JP and ~/.gtkrc.ja, and parses the first of those 
that exists. 


Pathnames and patterns 


A resource file defines a number of styles and key bindings and attaches them to particular widgets. The 
attachment is done by the widget, widget_class, and class declarations. As an example of such a statement: 


widget "mywindow.*.GtkEntry" style "my-entry-class" 


attaches the style "my-entry-class" to all widgets whose widget path matches the pattern 
"mywindow.*.GtkEntry". That is, all GtkEntry widgets which are part of a GtkWindow named "my- 
window". The patterns here are given in the standard shell glob syntax. The "?" wildcard matches any 
character, while "x" matches zero or more of any character. The three types of matching are against the 
widget path, the class path and the class hierarchy. Both the widget path and the class path consist of a 
"." separated list of all the parents of the widget and the widget itself from outermost to innermost. The 
difference is that in the widget path, the name assigned by gtk_widget_set_name() is used if present, oth- 
erwise the class name of the widget, while for the class path, the class name is always used. Widget_class 
paths can also contain <classname> substrings, which are matching the class with the given name and any 


derived classes. For instance, 


widget_class "*<GtkMenultem>.GtkLabel" style "my-style" 


will match GtkLabel widgets which are contained in any kind of menu item. So, if you have a GtkEn- 
try named "myentry", inside of a horizontal box in a window named "mywindow", then the widget path 
is: "mywindow.GtkHBox.myentry" while the class path is: "GtkWindow.GtkHBox.GtkEntry". Matching 
against class is a little different. The pattern match is done against all class names in the widgets class 
hierarchy (not the layout hierarchy) in sequence, so the pattern: 


class "GtkButton" style "my-style" 


will match not just GtkButton widgets, but also GtkToggleButton and GtkCheckButton widgets, since 
those classes derive from GtkButton. Additionally, a priority can be specified for each pattern, and styles 
override other styles first by priority, then by pattern type and then by order of specification (later overrides 
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earlier). The priorities that can be specified are (highest to lowest): highest rc theme application gtk lowest 
rc is the default for styles read from an RC file, theme is the default for styles read from theme RC files, 
application should be used for styles an application sets up, and gtk is used for styles that GTK+ creates 
internally. 


Everytime a widget is created and added to the layout hierarchy of a Gtk Window ("anchored" to be exact), 
a list of matching RC styles out of all RC styles read in so far is composed. For this, every RC style is 
matched against the widgets class path, the widgets name path and widgets inheritance hierarchy. As a 
consequence, significant slowdown can be caused by utilization of many RC styles and by using RC style 
patterns that are slow or complicated to match against a given widget. The following ordered list provides 
a number of advices (prioritized by effectiveness) to reduce the performance overhead associated with RC 
style matches: 


1. Move RC styles for specific applications into RC files dedicated to those applications and parse applica- 
tion specific RC files only from applications that are affected by them. This reduces the overall amount of 
RC styles that have to be considered for a match across a group of applications. 


2. Merge multiple styles which use the same matching rule, for instance: 


style "Foo" { foo_content } 
class "X" style "Foo" 
style "Bar" { bar_content } 


class "X" style "Bar" 


is faster to match as: 


style "FooBar" { foo_content bar_content } 
class "X" style "FooBar" 


3. Use of wildcards should be avoided, this can reduce the individual RC style match to a single integer 
comparison in most cases. 


4. To avoid complex recursive matching, specification of full class names (for class matches) or full path 


wow 


names (for widget and widget_class matches) is to be preferred over shortened names containing "x" or 
a a 


5. If at all necessary, wildcards should only be used at the tail or head of a pattern. This reduces the match 
complexity to a string comparison per RC style. 


Wow 


6. When using wildcards, use of "?" should be preferred over "x". This can reduce the matching complexity 
from O(n12) to O(n). For example "Gtk*Box" can be turned into "Gtk?Box" and will still match GtkHBox 
and Gtk VBox. 


T; The use of "x" wildcards should be restricted as much as possible, because matching 
"A*BxCxRestString” can result in matching complexities of O(n^2) worst case. 


Toplevel declarations 


An RC file is a text file which is composed of a sequence of declarations. ’#’ characters delimit comments 
and the portion of a line after a ’#’ is ignored when parsing an RC file. 


The possible toplevel declarations are: 
binding name { ... } Declares a binding set. 


class pattern [ style | binding ][ : priority ] name Specifies a style or binding set for a particular branch of 
the inheritance hierarchy. 


include filename Parses another file at this point. If filename is not an absolute filename, it is searched in 
the directories of the currently open RC files. 
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GTK+ also tries to load a locale-specific variant of the included file. 


module_path path Sets a path (a list of directories separated by colons) that will be searched for theme 
engines referenced in RC files. 


pixmap_path path Sets a path (a list of directories separated by colons) that will be searched for pixmaps 
referenced in RC files. 


im_module_file pathname Sets the pathname for the IM modules file. Setting this from RC files is depre- 
cated; you should use the environment variable GTK_IM_MODULE_FILE instead. 


style name [ = parent ] { ... } Declares a style. 


widget pattern [ style | binding ][ : priority ] name Specifies a style or binding set for a particular group of 
widgets by matching on the widget pathname. 


widget_class pattern [ style | binding ][ : priority ] name Specifies a style or binding set for a particular 
group of widgets by matching on the class pathname. 


setting = value Specifies a value for a setting. Note that settings in RC files are overwritten by system-wide 
settings (which are managed by an XSettings manager on X11). 


Styles 


A RC style is specified by a style declaration in a RC file, and then bound to widgets with a widget, 
widget_class, or class declaration. All styles applying to a particular widget are composited together with 
widget declarations overriding widget_class declarations which, in turn, override class declarations. Within 
each type of declaration, later declarations override earlier ones. 


Within a style declaration, the possible elements are: 
bg[state] = color Sets the color used for the background of most widgets. 
fe[state] = color Sets the color used for the foreground of most widgets. 


base[state] = color Sets the color used for the background of widgets displaying editable text. This color is 
used for the background of, among others, GtkText, GtkEntry, GtkList, and GtkCList. 


text[state] = color Sets the color used for foreground of widgets using base for the background color. 
xthickness = number Sets the xthickness, which is used for various horizontal padding values in GTK+. 
ythickness = number Sets the ythickness, which is used for various vertical padding values in GTK+. 


bg_pixmap[state] = pixmap Sets a background pixmap to be used in place of the bg color (or for GtkText, 
in place of the base color. The special value "<parent>" may be used to indicate that the widget should 
use the same background pixmap as its parent. The special value "<none>" may be used to indicate no 
background pixmap. 


font = font Starting with GTK+ 2.0, the "font" and "fontset" declarations are ignored; use "font_name" 
declarations instead. 


fontset = font Starting with GTK+ 2.0, the "font" and "fontset" declarations are ignored; use "font_name" 
declarations instead. 


font_name = font Sets the font for a widget. font must be a Pango font name, e.g. "Sans Italic 10". For 
details about Pango font names, see pango_font_description_from_string(). 


stock["stock-id"] = { icon source specifications } Defines the icon for a stock item. 


color["color-name"] = color specification Since 2.10, this element can be used to defines symbolic colors. 
See below for the syntax of color specifications. 


engine "engine" { engine-specific settings } Defines the engine to be used when drawing with this style. 
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class::property = value Sets a style property for a widget class. 
The colors and background pixmaps are specified as a function of the state of the widget. The states are: 
NORMAL A color used for a widget in its normal state. 


ACTIVE A variant of the NORMAL color used when the widget is in the GTK_STATE_ACTIVE state, 
and also for the trough of a ScrollBar, tabs of a NoteBook other than the current tab and similar areas. 
Frequently, this should be a darker variant of the NORMAL color. 


PRELIGHT A color used for widgets in the GTK_STATE_PRELIGHT state. This state is the used for 
Buttons and Menultems that have the mouse cursor over them, and for their children. 


SELECTED A color used to highlight data selected by the user. for instance, the selected items in a list 
widget, and the selection in an editable widget. 


INSENSITIVE A color used for the background of widgets that have been set insensitive with gtk_widget_- 
set_sensitive(). 


Colors can be specified as a string containing a color name (GTK+ knows all names from the X color 
database /usr/lib/X11/rgb.txt), in one of the hexadecimal forms rrrregggbbbb, rrrgggbbb, rrggbb, or rgb, 
where r, g and b are hex digits, or they can be specified as a triplet { r, g, b}, where r, g and b are either 
integers in the range 0-65535 or floats in the range 0.0-1.0. 


Since 2.10, colors can also be specified by refering to a symbolic color, as follows: -name, or by using 
expressions to combine colors. The following expressions are currently supported: 


mix (factor, color1, color2) Computes a new color by mixing color! and color2. The factor determines 
how close the new color is to colorl. A factor of 1.0 gives pure colorl, a factor of 0.0 gives pure color2. 


shade (factor, color) Computes a lighter or darker variant of color. A factor of 1.0 leaves the color un- 
changed, smaller factors yield darker colors, larger factors yield lighter colors. 


lighter (color) This is an abbreviation for shade (1.3, color). 
darker (color) This is an abbreviation for shade (0.7, color). 


Here are some examples of color expressions: 


mix (0.5, "red", "blue") 
shade (1.5, mix (0.3, "*0abbcO", { 0.3, 0.5, 0.9 })) 
lighter (@foreground) 


In a stock definition, icon sources are specified as a 4-tuple of image filename or icon name, text direction, 
widget state, and size, in that order. Each icon source specifies an image filename or icon name to use 
with a given direction, state, and size. Filenames are specified as a string such as "itemltr.png", while icon 
names (looked up in the current icon theme), are specified with a leading @, such as O"item-ltr". The x 
character can be used as a wildcard, and if direction/state/size are omitted they default to x. So for example, 
the following specifies different icons to use for left-to-right and right-to-left languages: 


stock["my-stock-item"] = 

{ 
{ "itemltr.png", LTR, *, * }, 
{ "itemrtl.png",; RTL; *, æ } 


This could be abbreviated as follows: 


stock["my-stock-item"] = 

{ 
{ “itemltr.png", LIR Fy 
{ "itemrtl.png", RTL } 
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You can specify custom icons for specific sizes, as follows: 

stock["my-stock-item"] = { { "itemmenusize.png", x, x, "gtk-menu" }, { "itemtoolbarsize.png", x, x, "gtk- 
large-toolbar" } { "itemgeneric.png" } // implicit x, x, x as a fallback | 

The sizes that come with GTK+ itself are "gtk-menu", "gtk-small-toolbar", "gtk-large-toolbar", "gtk- 


"n 


button", "gtk-dialog". Applications can define other sizes. 


It's also possible to use custom icons for a given state, for example: 


stock["my-stock-item"] = 
{ 
{ "itemprelight.png", *, PRELIGHT }, 
{ "iteminsensitive.png", *, INSENSITIVE }, 
{ "itemgeneric.png" } // implicit *, *, * as a fallback 


When selecting an icon source to use, GTK+ will consider text direction most important, state second, and 
size third. It will select the best match based on those criteria. If an attribute matches exactly (e.g. you 
specified PRELIGHT or specified the size), GTK+ won't modify the image; if the attribute matches with a 
wildcard, GTK+ will scale or modify the image to match the state and size the user requested. 


Key bindings 


Key bindings allow the user to specify actions to be taken on particular key presses. The form of a binding 
set declaration is: 


binding name { 
bind key { 
signalname (param, ...) 


key is a string consisting of a series of modifiers followed by the name of a key. The modifiers can be: 


<alt> <ctl> <control> <meta> <hyper> <super> <mod1> <mod2> <mod3> <mod4> <mod5> 
<release> <shft> <shift> 


<shft> is an alias for <shift>, <ctl> is an alias for <control>, and <alt> is an alias for <modl>. 


The action that is bound to the key is a sequence of signal names (strings) followed by parameters for each 
signal. The signals must be action signals. (See g_signal_new()). Each parameter can be a float, integer, 
string, or unquoted string representing an enumeration value. The types of the parameters specified must 
match the types of the parameters of the signal. 


Binding sets are connected to widgets in the same manner as styles, with one difference: Binding sets 
override other binding sets first by pattern type, then by priority and then by order of specification. The 
priorities that can be specified and their default values are the same as for styles. 


Data Structures 


e struct _GtkRcStyle 


GtkRcStyle instance structure. 


e struct _GtkRcStyleClass 


GtkRcStyle instance class structure. 
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e struct _GtkRcProperty 


rc properties (structure forward declared in gtkstyle.h) 


Functions 


e void gtk_rc_add_default_file (const gchar +filename) 
Adds a file to the list of files to be parsed at the end of gtk_init(). 


e void gtk_rc_set_default_files (gchar «*filenames) 
Sets the list of files that GTK+ will read at the end of gtk_init(). 


e gchar ** gtk_rc_get_default_files (void) 


Retrieves the current list of RC files that will be parsed at the end of gtk_init(). 


e GtkStyle * gtk_rc_get_style (GtkWidget *widget) 


Finds all matching RC styles for a given widget, composites them together, and then creates a GtkStyle 
representing the composite appearance. 


e GtkStyle x* gtk_rc_get_style_by_paths (GtkSettings *settings, const char *widget_path, const char 
*class_ path, GType type) 


Creates up a GtkStyle from styles defined in a RC file by providing the raw components used in matching. 


e gboolean gtk_rc_reparse_all_for_settings (GtkSettings *settings, gboolean force_load) 


If the modification time on any previously read file for the given GtkSettings has changed, discard all style 
information and then reread all previously read RC files. 


e void gtk_rc_reset_styles (GtkSettings *settings) 


This function recomputes the styles for all widgets that use a particular GtkSettings object. 


e gchar x gtk_rc_find _pixmap_in path (GtkSettings settings, GScanner *scanner, const gchar 
*pixmap_file) 


Looks up a file in pixmap path for the specified GtkSettings. 


e void gtk_rc_parse (const gchar *filename) 


Parses a given resource file. 


e void gtk_rc_parse_string (const gchar *rc_string) 


Parses resource information directly from a string. 


e gboolean gtk_rc_reparse_all (void) 


If the modification time on any previously read file for the default GtkSettings has changed, discard all style 
information and then reread all previously read RC files. 


e GtkRcStyle * gtk_rc_style_new (void) 


Creates a new GtkRcStyle with no fields set and a reference count of 1. 


e GtkRcStyle x* gtk_rc_style_copy (GtkRcStyle xorig) 
Makes a copy of the specified GtkRcStyle. 
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e void gtk_rc_style_ref (GtkRcStyle x*rc_style) 


Increments the reference count of a GtkRcStyle. 


e void gtk_rc_style_unref (GtkRcStyle x*rc_style) 


Decrements the reference count of a GtkRcStyle and frees if the result is 0. 


e gchar * gtk_rc_find_module_in_path (const gchar *module_file) 


Searches for a theme engine in the GTK+ search path. 


e gchar * gtk_rc_get_theme_dir (void) 


Returns the standard directory in which themes should be installed. 


e gchar * gtk_rc_get_module_dir (void) 


Returns a directory in which GTK+ looks for theme engines. 


e gchar * gtk_rc_get_im_module_path (void) 


Obtains the path in which to look for IM modules. 


e gchar * gtk_rc_get_im_module_file (void) 
Obtains the path to the IM modules file. 


e GScanner x gtk_rc_scanner_new (void) 


Creates a new GScanner widget. 


e guint gtk_rc_parse_color (GScanner scanner, GdkColor *color) 


Parses a color in the format expected in a RC file. 


e guint gtk_rc_parse_state (GScanner «scanner, GtkStateType *state) 


Parses a GtkStateType variable from the format expected in a RC file. 


e guint gtk_rc_parse_priority (GScanner «scanner, GtkPathPriorityType «priority) 
Parses a GtkPathPriorityType variable from the format expected in a RC file. 


6.4.2 Function Documentation 


6.4.2.1 void gtk_rc_add_default_file (const gchar x filename) 


Adds a file to the list of files to be parsed at the end of gtk_init(). 


Parameters: 


filename [in] the pathname to the file. If filename is not absolute, it is searched in the current directory 


Returns: 


void 
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6.4.2.2 gchar» gtk_rc_find_module_in_path (const gchar « module_file) 


Searches for a theme engine in the GTK+ search path. 


This function is not useful for applications and should not be used. 


Parameters: 


module_file [in] name of a theme engine 


Returns: 


The filename, if found (must be freed with g_free()), otherwise NULL. 


6.4.2.3 gchar» gtk_rc_find_pixmap_in_path (GtkSettings x settings, GScanner x scanner, const 
gchar x pixmap_file) 


Looks up a file in pixmap path for the specified GtkSettings. 


If the file is not found, it outputs a warning message using g_warning() and returns NULL. 


Parameters: 
settings [in] a GtkSettings 
scanner [in] Scanner used to get line number information for the warning message, or NULL 


pixmap_file [in] name of the pixmap file to locate. 


Returns: 


the filename. 


6.4.2.4 gcharxx gtk_rc_get_default_files (void) 


Retrieves the current list of RC files that will be parsed at the end of gtk_init(). 


Returns: 


A NULL-terminated array of filenames. This memory is owned by GTK+ and must not be freed by 
the application. If you want to store this information, you should make a copy. 


6.4.2.5 gcharx gtk_rc_get_im_module_file (void) 


Obtains the path to the IM modules file. 
See the documentation of the GTK_IM_MODULE_FILE environment variable for more details. 


Returns: 


a newly-allocated string containing the name of the file listing the IM modules available for loading 
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6.4.2.6 gcharx gtk_rc_get_im_module_path (void) 


Obtains the path in which to look for IM modules. 


See the documentation of the GTK_PATH environment variable for more details about looking up modules. 
This function is useful solely for utilities supplied with GTK+ and should not be used by applications under 
normal circumstances. 


Returns: 


a newly-allocated string containing the path in which to look for IM modules. 


6.4.2.7 gcharx gtk_rc_get_module_dir (void) 


Returns a directory in which GTK+ looks for theme engines. 

For full information about the search for theme engines, see the docs for GTK_PATH in Running GTK+ 
Applications(3). 

Returns: 


the directory. (Must be freed with g_free()) 


6.4.2.8 GtkStylex gtk_rc_get_style (GtkWidget « widget) 
Finds all matching RC styles for a given widget, composites them together, and then creates a GtkStyle 
representing the composite appearance. 


(GTK+ actually keeps a cache of previously created styles, so a new style may not be created.) 


Parameters: 


widget [in] a GtkWidget 


Returns: 


the resulting style. No refcount is added to the returned style, so if you want to save this style around, 
you should add a reference yourself. 


6.4.2.9 GtkStylex gtk_rc_get_style_by_paths (GtkSettings x settings, const char « widget_path, 
const char « class_path, GType type) 


Creates up a GtkStyle from styles defined in a RC file by providing the raw components used in matching. 


This function may be useful when creating pseudo-widgets that should be themed like widgets but don't 
actually have corresponding GTK+ widgets. An example of this would be items inside a GNOME canvas 
widget. The action of gtk_rc_ get_style() is similar to: 


gtk_widget_path (widget, NULL, path, NULL); 

gtk_widget_class_path (widget, NULL, &class_path, NULL); 

gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path, 
G_OBJECT_TYPE (widget)); 


Parameters: 


settings [in] a GtkSettings object 
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widget_path [in] the widget path to use when looking up the style, or NULL if no matching against 
the widget path should be done 


class_path [in] the class path to use when looking up the style, or NULL if no matching against the 
class path should be done. 


type [in] a type that will be used along with parent types of this type when matching against class 
styles, or G_TYPE_NONE 


Returns: 


A style created by matching with the supplied paths, or NULL if nothing matching was specified and 
the default style should be used. The returned value is owned by GTK+ as part of an internal cache, so 
you must call g_object_ref() on the returned value if you want to keep a reference to it. 


6.4.2.10 gchar» gtk_rc_get_theme_dir (void) 


Returns the standard directory in which themes should be installed. 


(GTK+ does not actually use this directory itself.) 


Returns: 


The directory (must be freed with g_free()). 


6.4.2.11 void gtk_rc_parse (const gchar « filename) 


Parses a given resource file. 


Parameters: 


filename [in] the filename of a file to parse. If filename is not absolute, it is searched in the current 
directory. 


Returns: 


void 


6.4.2.12 guint gtk_rc_parse_color (GScanner * scanner, GdkColor x color) 


Parses a color in the format expected in a RC file. 
Parameters: 


scanner [in] a GtkScanner 


color [in] a pointer to a GtkColor structure in which to store the result 


Returns: 


G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found. 
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6.4.2.13 guint gtk_rc_parse_priority (GScanner x scanner, GtkPathPriorityType x priority) 


Parses a GtkPathPriorityType variable from the format expected in a RC file. 


Parameters: 
filename [in] a GtkScanner (must be initialized for parsing an RC file) 


priority [in] A pointer to GtkPathPriorityType variable in which to store the result. 


Returns: 


G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found. 


6.4.2.14 guint gtk_rc_parse_state (GScanner « scanner, GtkStateType + state) 


Parses a GtkStateType variable from the format expected in a RC file. 


Parameters: 
scanner [in] a GtkScanner (must be initialized for parsing an RC file) 


state [in] A pointer to a GtkStateType variable in which to store the result. 


Returns: 


G_TOKEN_NONE if parsing succeeded, otherwise the token that was expected but not found. 


6.4.2.15 void gtk_rc_parse_string (const gchar + rc_string) 


Parses resource information directly from a string. 


Parameters: 


rc_string [in] a string to parse. 


Returns: 


void 


6.4.2.16 gboolean gtk_rc_reparse_all (void) 


If the modification time on any previously read file for the default GtkSettings has changed, discard all 
style information and then reread all previously read RC files. 


Returns: 


TRUE if the files were reread. 
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6.4.2.17 gboolean gtk_rc_reparse_all_for_settings (GtkSettings x settings, gboolean force_load) 


If the modification time on any previously read file for the given GtkSettings has changed, discard all style 
information and then reread all previously read RC files. 


Parameters: 
settings [in] a GtkSettings 
force_load [in] load whether or not anything changed 


Returns: 


TRUE if the files were reread. 


6.4.2.18 void gtk_rc_reset_styles (GtkSettings « settings) 


This function recomputes the styles for all widgets that use a particular GtkSettings object. 


(There is one GtkSettings object per GdkScreen, see gtk_settings_get_for_screen()); It is useful when some 
global parameter has changed that affects the appearance of all widgets, because when a widget gets a new 
style, it will both redraw and recompute any cached information about its appearance. As an example, it is 
used when the default font size set by the operating system changes. Note that this function doesn’t affect 
widgets that have a style set explicitely on them with gtk_widget_set_style(). 


Parameters: 


settings [in] a GtkSettings 


Returns: 


void 


6.4.2.19 GScanner« gtk_rc_scanner_new (void) 
Creates a new GScanner widget. 


Returns: 


new GScanner 


6.4.2.20 void gtk_rc_set_default_files (gchar x* filenames) 
Sets the list of files that GTK+ will read at the end of gtk_init(). 


Parameters: 


filenames [in] A NULL-terminated list of filenames. 


Returns: 


void 
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6.4.2.21 GtkRcStylex gtk_rc_style_copy (GtkRcStyle x orig) 


Makes a copy of the specified GtkRcStyle. 


This function will correctly copy an RC style that is a member of a class derived from GtkRcStyle 


Parameters: 


orig [in] the style to copy 


Returns: 


the resulting GtkRcStyle 


6.4.2.22 GtkRcStyle« gtk_rc_style_new (void) 


Creates a new GtkRcStyle with no fields set and a reference count of 1. 


Returns: 


the newly-created GtkRcStyle 


6.4.2.23 void gtk_rc_style_ref (GtkRcStyle x rc_style) 
Increments the reference count of a GtkRcStyle. 


Parameters: 


rc_style [in] a GtkRcStyle 


Returns: 


void 


6.4.2.24 void gtk_rc_style_unref (GtkRcStyle x rc_style) 


Decrements the reference count of a GtkRcStyle and frees if the result is 0. 


Parameters: 


rc_style [in] a GtkRcStyle 


Returns: 


void 
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6.5 GtkSettings 


6.5.1 Detailed Description 


This file implements the Sharing settings between applications. 


Data Structures 


e struct _GtkSettings 


GtkSettings instance structure. 


e struct _GtkSettingsClass 


GtkSettings instance class structure. 


Functions 


e GtkSettings * gtk_settings_get_default (void) 


Gets the GtkSettings object for the default GDK screen, creating it if necessary. 


e GtkSettings * gtk_settings_get_for_screen (GdkScreen *screen) 


Gets the GtkSettings object for screen, creating it if necessary. 


e void gtk_settings_install_property (GParamSpec *pspec) 


Install new property. 


e void gtk_settings_install_property_parser (GParamSpec *pspec, GtkRcPropertyParser parser) 


Install the property parser. 


e gboolean gtk_rc_property_parse_color (const GParamSpec xpspec, const GString *gstring, GValue 
*property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses a color given either by its name or in the form { red, green, blue } 
where red, green and blue are integers between 0 and 65535 or floating-point numbers between 0 and 1. 


e gboolean gtk_rc_property_parse_enum (const GParamSpec *pspec, const GString *gstring, GValue 
*property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses a single enumeration value. 


e gboolean gtk_rc_property_parse_flags (const GParamSpec *pspec, const GString *gstring, GValue 
*property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses flags. 


e gboolean gtk_rc_property_parse_requisition (const GParamSpec *pspec, const GString *gstring, 
GValue x*property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses a requisition in the form "{ width, height }" for integers width and 
height. 
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e gboolean gtk_rc_property_parse_border (const GParamSpec x*pspec, const GString *gstring, GValue 
*property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses borders in the form "{ left, right, top, bottom }" for integers left, right, 
top and bottom. 


e void gtk settings_set_property_value (GtkSettings settings, const gchar xname, const GtkSet- 
tings Value *svalue) 


sets the property value with the given value 


e void gtk_settings_set_string_property (GtkSettings settings, const gchar xname, const gchar *v_- 
string, const gchar xorigin) 


sets the string property 


e void gtk_settings_set_long_property (GtkSettings «settings, const gchar xname, glong v_long, const 
gchar *origin) 


sets the lonf property of the object 


e void gtk _settings_set_double_property (GtkSettings *settings, const gchar xname, gdouble v_- 
double, const gchar *origin) 


sets the double property 


e GtkSettings * gtk_settings_create_global_settings_object () 


creatres global setting object 


6.5.2 Function Documentation 


6.5.2.1 gboolean gtk_rc_property_parse_border (const GParamSpec * pspec, const GString + 
gstring, GValue x property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses borders in the form "{ left, right, top, bottom }" for integers left, 
right, top and bottom. 


Parameters: 


pspec [in] a GParamSpec 
gstring [in] the GString to be parsed 
property_value [in] a GValue which must hold boxed values. 


Returns: 


TRUE if gstring could be parsed and property_value has been set to the resulting GtkBorder. 


6.5.2.2 gboolean gtk_rc_property_parse_color (const GParamSpec * pspec, const GString * 
gstring, GValue x property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses a color given either by its name or in the form { red, green, blue } 
where red, green and blue are integers between 0 and 65535 or floating-point numbers between 0 and 1. 
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Parameters: 
pspec [in] a GParamSpec 
gstring [in] the GString to be parsed 
property_value [in] a GValue which must hold GdkColor values. 


Returns: 


TRUE if gstring could be parsed and property_value has been set to the resulting GdkColor. 


6.5.2.3 gboolean gtk_rc_property_parse_enum (const GParamSpec x pspec, const GString x 
gstring, GValue x property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses a single enumeration value. 


The enumeration value can be specified by its name, its nickname or its numeric value. For consistency 
with flags parsing, the value may be surrounded by parentheses. 
Parameters: 

pspec [in] a GParamSpec 

gstring [in] the GString to be parsed 


property_value [in] a GValue which must hold enum values. 


Returns: 


TRUE if gstring could be parsed and property_value has been set to the resulting GEnumValue. 


6.5.2.4 gboolean gtk_rc_property_parse_flags (const GParamSpec x pspec, const GString + 
gstring, GValue x property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses flags. 


Flags can be specified by their name, their nickname or numerically. Multiple flags can be specified in the 
form "(flagl | flag2 |... )”. 
Parameters: 

pspec [in] a GParamSpec 

gstring [in] the GString to be parsed 


property_value [in] a GValue which must hold flags values. 


Returns: 


TRUE if gstring could be parsed and property_value has been set to the resulting flags value. 
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6.5.2.5 gboolean gtk_rc_property_parse_requisition (const GParamSpec * pspec, const GString * 
gstring, GValue x property_value) 


A GtkRcPropertyParser for use with gtk_settings_install_property_parser() or gtk_widget_class_install_- 
style_property_parser() which parses a requisition in the form "{ width, height }" for integers width and 
height. 


Parameters: 
pspec [in] a GParamSpec 
gstring [in] the GString to be parsed 


property_value [in] a GValue which must hold boxed values. 


Returns: 


TRUE if gstring could be parsed and property_value has been set to the resulting GtkRequisition. 


6.5.2.6 GtkSettingsx gtk_settings_create_global_settings_object () 


creatres global setting object 


Returns: 


a newly created GtkSettings object 


Since 


LIMO R1 


6.5.2.7 GtkSettingsx gtk_settings_get_default (void) 


Gets the GtkSettings object for the default GDK screen, creating it if necessary. 


See gtk_settings_get_for_screen(). 


Returns: 


a GtkSettings object. If there is no default screen, then returns NULL. 


6.5.2.8 GtkSettingsx gtk_ settings _get_for_screen (GdkScreen x screen) 


Gets the GtkSettings object for screen, creating it if necessary. 


Parameters: 


screen [in] a GdkScreen. 


Returns: 


a GtkSettings object. 
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6.5.2.9 void gtk_settings_install_property (GParamSpec * pspec) 


Install new property. 


Parameters: 


screen [in] a GParamSpec. 


Returns: 


void 


6.5.2.10 void gtk_settings_install_property_parser (GParamSpec + pspec, GtkRcPropertyParser 
parser) 


Install the property parser. 


Parameters: 


screen [in] a GdkScreen. 


parser [in] a GtkRcPropertyParser. 


Returns: 


void 


6.5.2.11 void gtk_settings_set_double_property (GtkSettings x settings, const gchar x name, 
gdouble v_double, const gchar x origin) 


sets the double property 


Parameters: 
settings [in] a GtkSettings 
name [in] String name 
v_double [in] v_double 


origin [in] origin 


Returns: 


void 


6.5.2.12 void gtk_settings_set_long_property (GtkSettings x settings, const gchar * name, glong 
v_long, const gchar x origin) 


sets the lonf property of the object 


Parameters: 


pspec [in] a GtkSettings 
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name [in] string name 

v_long [in] v_long 

origin [in] origin 
Returns: 


void 


6.5.2.13 void gtk_settings_set_property_value (GtkSettings x settings, const gchar * name, const 
GtkSettings Value x svalue) 


sets the property value with the given value 


Parameters: 
settings [in] a GtkSettings 
name [in] String 


svalue [in] a GtkSettings Value 


Returns: 


void 


6.5.2.14 void gtk_settings_set_string_ property (GtkSettings x settings, const gchar x name, const 
gchar x v_string, const gchar * origin) 


sets the string property 


Parameters: 
settings [in] a GtkSettings 
name [in] String 
v_string [in] v_string 


origin [in] origin 


Returns: 


void 
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6.6 GtkStyle 


6.6.1 Detailed Description 


This GtkStyle widget provide Functions for drawing widget parts. 
Code Example 
GtkStyle *style; 


GdkColor coll; 
GdkColor col2; 


coll.red = 56000; 
coll.green = 0; 
coll.blue = 0; 
col2.red = 0; 
col2.green = 56000; 
col2.blue = 32000; 


style = gtk_style_new (); 

style->fg[GTK_STATE_NORMAL] = coll; 

style->base[GTK_STATE_NORMAL] = col2; 

pango_font_description_set_size (style->font_desc, 14 * PANGO_SCALE) ; 
pango_font_description_set_weight (style->font_desc, PANGO_WEIGHT_BOLD); 
gtk_style_unref (style); 


Data Structures 


e struct _GtkStyle 


GtkStyle instance structure. 


e struct _GtkStyleClass 


GtkStyle instance class structure. 


Functions 


GtkStyle x gtk_style_new (void) 
Creates a new GtkStyle. 


GtkStyle * gtk_style_copy (GtkStyle style) 
Copies a GtkStyle structure. 


GtkStyle * gtk_style_attach (GtkStyle «style, Gdk Window *window) 


Attaches a style to a window; this process allocates the colors and creates the GC’s for the style - it special- 
izes it to a particular visual and colormap. 


e void gtk_style_detach (GtkStyle *style) 


Detaches a style from a window. 


e void gtk_style_set_background (GtkStyle «style, GdkWindow *window, GtkStateType state_type) 


Sets the background of window to the background color or pixmap specified by style for the given state. 
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void gtk_style_apply_default_background (GtkStyle «style, GdkWindow *window, gboolean set_- 
bg, GtkStateType state_type, GdkRectangle «area, gint x, gint y, gint width, gint height) 


Sets the background of window to the background color using the given parameters. 


GtkIconSet * gtk_style_lookup_icon_set (GtkStyle *style, const gchar *stock_id) 


fn: gtk_style_lookup_icon_set 


gboolean gtk_style_lookup_color (GtkStyle *style, const gchar *«color_name, GdkColor x*color) 


Looks up color_name in the style’s logical color mappings, filling in color and returning TRUE if found, 
otherwise returning FALSE. 


GdkPixbuf * gtk_style_render_icon (GtkStyle *style, const GtkIconSource *source, GtkTextDirec- 
tion direction, GtkStateType state, GtkIconSize size, GtkWidget *widget, const gchar *detail) 


Renders the icon specified by source at the given size according to the given parameters and returns the 
result in a pixbuf. 


void gtk_paint_hline (GtkStyle «style, GdkWindow «window, GtkStateType state_type, GdkRectan- 
gle xarea, GtkWidget «widget, const gchar x*detail, gint x1, gint x2, gint y) 


Draws a horizontal line from (x1, y) to (x2, y) in window using the given style and state. 


void gtk_paint_vline (GtkStyle «style, GdkWindow «window, GtkStateType state_type, GdkRectan- 
gle xarea, GtkWidget *widget, const gchar «detail, gint y1_, gint y2_, gint x) 


Draws a vertical line from (x, y! _) to (x, y2_) in window using the given style and state. 


void gtk_paint_shadow (GtkStyle «style, Gdk Window window, GtkStateType state_type, GtkShad- 
owType shadow_type, GdkRectangle xarea, GtkWidget «widget, const gchar «detail, gint x, gint y, 
gint width, gint height) 


Draws a shadow around the given rectangle in window using the given style and state and shadow type. 


void gtk_paint_polygon (GtkStyle «style, GdkWindow window, GtkStateType state_type, Gtk- 
ShadowType shadow_type, GdkRectangle xarea, Gtk Widget *widget, const gchar *detail, GdkPoint 
*points, gint npoints, gboolean fill) 


Draws a polygon on window with the given parameters. 


void gtk_paint_arrow (GtkStyle «style, GdkWindow «window, GtkStateType state_type, GtkShad- 
owType shadow_type, GdkRectangle xarea, Gtk Widget «widget, const gchar «detail, GtkArrowType 
arrow_type, gboolean fill, gint x, gint y, gint width, gint height) 


Draws an arrow in the given rectangle on window using the given parameters. 


void gtk_paint_diamond (GtkStyle «style, GdkWindow «window, GtkStateType state_type, Gtk- 
ShadowType shadow_type, GdkRectangle xarea, GtkWidget «widget, const gchar *detail, gint x, 
gint y, gint width, gint height) 


Draws a diamond in the given rectangle on window using the given parameters. 


void gtk_paint_box (GtkStyle «style, GdkWindow «window, GtkStateType state_type, GtkShadow- 
Type shadow_type, GdkRectangle xarea, GtkWidget «widget, const gchar «detail, gint x, gint y, gint 
width, gint height) 


Draws a box on window with the given parameters. 
void gtk_paint_flat_box (GtkStyle «style, GdkWindow window, GtkStateType state_type, Gtk- 


ShadowType shadow_type, GdkRectangle xarea, GtkWidget «widget, const gchar x*detail, gint x, 
gint y, gint width, gint height) 
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Draws a flat box on window with the given parameters. 


void gtk_paint_check (GtkStyle «style, GdkWindow *window, GtkStateType state_type, GtkShad- 
owType shadow_type, GdkRectangle xarea, GtkWidget *widget, const gchar «detail, gint x, gint y, 
gint width, gint height) 


Draws a check button indicator in the given rectangle on window with the given parameters. 


void gtk_paint_option (GtkStyle *style, GdkWindow *window, GtkStateType state_type, GtkShad- 
owType shadow_type, GdkRectangle xarea, GtkWidget *widget, const gchar «detail, gint x, gint y, 
gint width, gint height) 


Draws a radio button indicator in the given rectangle on window with the given parameters. 


void gtk_paint_tab (GtkStyle «style, GdkWindow *window, GtkStateType state_type, GtkShadow- 
Type shadow_type, GdkRectangle xarea, GtkWidget «widget, const gchar «detail, gint x, gint y, gint 
width, gint height) 


Draws an option menu tab (i.e. 


void gtk_paint_shadow_gap (GtkStyle «style, GdkWindow «window, GtkStateType state_type, Gtk- 
ShadowType shadow_type, GdkRectangle xarea, GtkWidget «widget, gchar *detail, gint x, gint y, 
gint width, gint height, GtkPositionType gap_side, gint gap_x, gint gap_width) 
Draws a shadow around the given rectangle in window using the given style and state and shadow type, 
leaving a gap in one side. 


void gtk_paint_box_gap (GtkStyle x*style, GdkWindow *window, GtkStateType state_type, Gtk- 
ShadowType shadow_type, GdkRectangle xarea, GtkWidget «widget, gchar *detail, gint x, gint y, 
gint width, gint height, GtkPositionType gap_side, gint gap_x, gint gap_width) 


Draws a box in window using the given style and state and shadow type, leaving a gap in one side. 


void gtk_paint_extension (GtkStyle «style, GdkWindow «window, GtkStateType state_type, Gtk- 
ShadowType shadow_type, GdkRectangle xarea, GtkWidget «widget, gchar *detail, gint x, gint y, 
gint width, gint height, GtkPositionType gap_side) 


Draws an extension, i.e. 


void gtk_paint_focus (GtkStyle «style, GdkWindow window, GtkStateType state_type, GdkRect- 
angle xarea, GtkWidget «widget, const gchar *detail, gint x, gint y, gint width, gint height) 


Draws a focus indicator around the given rectangle on window using the given style. 


void gtk_paint_slider (GtkStyle «style, GdkWindow «window, GtkStateType state_type, GtkShad- 
owType shadow_type, GdkRectangle xarea, GtkWidget «widget, const gchar «detail, gint x, gint y, 
gint width, gint height, GtkOrientation orientation) 


Draws a handle as used in GtkHandleBox and GtkPaned. 


void gtk_paint_handle (GtkStyle «style, Gdk Window «window, GtkStateType state_type, GtkShad- 
owType shadow_type, GdkRectangle xarea, GtkWidget «widget, const gchar «detail, gint x, gint y, 
gint width, gint height, GtkOrientation orientation) 


Draws a handle as used in GtkHandleBox and GtkPaned. 


void gtk_paint_expander (GtkStyle «style, GdkWindow «window, GtkStateType state_type, Gd- 
kRectangle xarea, GtkWidget «widget, const gchar «detail, gint x, gint y, GtkExpanderStyle 
expander_style) 


Draws an expander as used in GtkTree View. 
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void gtk_paint_layout (GtkStyle *style, GdkWindow *window, GtkStateType state_type, gboolean 
use_text, GdkRectangle «area, GtkWidget *widget, const gchar «detail, gint x, gint y, PangoLayout 
*layout) 


Draws a layout on window using the given parameters. 


void gtk_paint_resize_grip (GtkStyle «style, GdkWindow window, GtkStateType state_type, Gd- 
kRectangle xarea, GtkWidget «widget, const gchar *detail, GdkWindowEdge edge, gint x, gint y, 
gint width, gint height) 


Draws a resize grip in the given rectangle on window using the given parameters. 


GtkBorder * gtk _border_copy (const GtkBorder *border_) 


Copies a GtkBorder structure. 


void gtk_border_free (GtkBorder *border_) 


Frees a GtkBorder structure. 


void gtk draw_insertion_cursor (GtkWidget «widget, GdkDrawable «drawable, GdkRectangle 
xarea, GdkRectangle *location, gboolean is_primary, GtkTextDirection direction, gboolean draw_- 
arrow) 


Draws a text caret on drawable at location. 


6.6.2 Function Documentation 
6.6.2.1 GtkBorderx gtk_border_copy (const GtkBorder x border_) 


Copies a GtkBorder structure. 


Parameters: 


border_ [in] a GtkBorder. 


Returns: 


a copy of border_. 


6.6.2.2 void gtk_border_free (GtkBorder x border_) 
Frees a GtkBorder structure. 


Parameters: 


border_ [in] a GtkBorder. 


Returns: 


void 
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6.6.2.3 void gtk_draw_insertion_cursor (GtkWidget « widget, GdkDrawable « drawable, 
GdkRectangle x area, GdkRectangle x location, gboolean is_primary, GtkTextDirection 
direction, gboolean draw_arrow) 


Draws a text caret on drawable at location. 


This is not a style function but merely a convenience function for drawing the standard cursor shape. 


Parameters: 
widget [in] a GtkWidget 
drawable [in] a GdkDrawable 
area [in] rectangle to which the output is clipped, or NULL if the output should not be clipped 
location [in] location where to draw the cursor (location->width is ignored) 
is_primary [in] if the cursor should be the primary cursor color. 


direction [in] whether the cursor is left-to-right or right-to-left. Should never be GTK_TEXT_DIR_- 
NONE 


draw_arrow [in] TRUE to draw a directional arrow on the cursor. Should be FALSE unless the cursor 
is split. 


Returns: 


void 


6.6.2.4 void gtk_paint_arrow (GtkStyle x style, GdkWindow x window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle x area, GtkWidget « widget, const gchar + 
detail, GtkArrowType arrow_type, gboolean fill, gint x, gint y, gint width, gint height) 


Draws an arrow in the given rectangle on window using the given parameters. 


arrow_type determines the direction of the arrow. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
arrow_type [in] the type of arrow to draw 
fill [in] TRUE if the arrow tip should be filled 
x [in] x origin of the rectangle to draw the arrow in 
y [in] y origin of the rectangle to draw the arrow in 
width [in] width of the rectangle to draw the arrow in 


height [in] height of the rectangle to draw the arrow in 


Returns: 


void 
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6.6.2.5 void gtk_paint_box (GtkStyle x style, GdkWindow « window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle x area, GtkWidget « widget, const gchar + 
detail, gint x, gint y, gint width, gint height) 


Draws a box on window with the given parameters. 


Parameters: 


style [in] a GtkStyle 

window [in] a GdkWindow 

state_type [in] a state 

shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the box 

y [in] y origin of the box 

width [in] the width of the box 

height [in] the height of the box 


Returns: 


void 


6.6.2.6 void gtk_paint_box_gap (GtkStyle x style, GdkWindow * window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle « area, GtkWidget * widget, gchar + detail, 
gint x, gint y, gint width, gint height, GtkPositionType gap_side, gint gap_x, gint gap_width) 


Draws a box in window using the given style and state and shadow type, leaving a gap in one side. 


Parameters: 


style [in] a GtkStyle 

window [in] a GdkWindow 

state_type [in] a state 

shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 

x [in] x origin of the extension 

y [in] y origin of the extension 

width [in] width of the extension 

height [in] height of the extension 
gap_side [in] side in which to leave the gap 
gap_x [in] starting position of the gap 
gap_width [in] width of the gap 


Returns: 


void 
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6.6.2.7 void gtk_paint_check (GtkStyle x style, GdkWindow « window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle x area, GtkWidget « widget, const gchar + 
detail, gint x, gint y, gint width, gint height) 


Draws a check button indicator in the given rectangle on window with the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the rectangle to draw the check in 
y [in] y origin of the rectangle to draw the check in 
width [in] the width of the rectangle to draw the check in 
height [in] the height of the rectangle to draw the check in 


Returns: 


void 


6.6.2.8 void gtk_paint_diamond (GtkStyle x style, Gdk Window « window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle x area, GtkWidget « widget, const gchar + 
detail, gint x, gint y, gint width, gint height) 


Draws a diamond in the given rectangle on window using the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the rectangle to draw the diamond in 
y [in] y origin of the rectangle to draw the diamond in 
width [in] width of the rectangle to draw the diamond in 


height [in] height of the rectangle to draw the diamond in 


Returns: 


void 
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6.6.2.9 void gtk paint_expander (GtkStyle x style, GdkWindow x window, GtkStateType 
state_type, GdkRectangle x area, GtkWidget x widget, const gchar x detail, gint x, gint y, 
GtkExpanderStyle expander_style) 


Draws an expander as used in GtkTreeView. 


x and y specify the center the expander. The size of the expander is determined by the "expander-size" style 
property of widget. (If widget is not specified or doesn’t have an "expander-size" property, an unspecified 
default size will be used, since the caller doesn’t have sufficient information to position the expander, this 
is likely not useful.) The expander is expander_size pixels tall in the collapsed position and expander_size 
pixels wide in the expanded position. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] the x position to draw the expander at 
y [in] the y position to draw the expander at 


expander_style [in] the style to draw the expander in; determines whether the expander is collapsed, 
expanded, or in an intermediate state. 


Returns: 


void 


6.6.2.10 void gtk_paint_extension (GtkStyle x style, GdkWindow « window, GtkStateType 
state_type, GtkShadowType shadow_type, GdkRectangle x area, GtkWidget * widget, 
gchar x detail, gint x, gint y, gint width, gint height, GtkPositionType gap_side) 


Draws an extension, i.e. 


a notebook tab. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the extension 
y [in] y origin of the extension 


width [in] width of the extension 
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height [in] height of the extension 


gap_side [in] the side on to which the extension is attached 


Returns: 


void 


6.6.2.11 void gtk_paint_flat_box (GtkStyle x style, GdkWindow * window, GtkState Type 
state_type, GtkShadowType shadow_type, GdkRectangle « area, Gtk Widget x widget, const 
gchar x detail, gint x, gint y, gint width, gint height) 


Draws a flat box on window with the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the box 
y [in] y origin of the box 
width [in] the width of the box 
height [in] the height of the box 


Returns: 


void 


6.6.2.12 void gtk_paint_focus (GtkStyle x style, GdkWindow « window, GtkStateType state_type, 
GdkRectangle « area, GtkWidget « widget, const gchar « detail, gint x, gint y, gint width, 
gint height) 


Draws a focus indicator around the given rectangle on window using the given style. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] the x origin of the rectangle around which to draw a focus indicator 
y [in] the y origin of the rectangle around which to draw a focus indicator 
width [in] the width of the rectangle around which to draw a focus indicator 


height [in] the height of the rectangle around which to draw a focus indicator 
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6.6.2.13 void gtk_paint_handle (GtkStyle x style, GdAkWindow * window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle x area, GtkWidget « widget, const gchar x 
detail, gint x, gint y, gint width, gint height, GtkOrientation orientation) 


Draws a handle as used in GtkHandleBox and GtkPaned. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
area [in] type of shadow to draw 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the handle 
y [in] y origin of the handle 
width [in] width of the handle 
height [in] height of the handle 


orientation [in] the orientation of the handle 


Returns: 


void 


6.6.2.14 void gtk_paint_hline (GtkStyle x style, GdkWindow x window, GtkStateType state_type, 
GdkRectangle « area, GtkWidget « widget, const gchar + detail, gint x1, gint x2, gint y) 


Draws a horizontal line from (x1, y) to (x2, y) in window using the given style and state. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
area [in] rectangle to which the output is clipped, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x1 [in] the starting x coordinate 
x1 [in] the ending x coordinate 


y [in] the y coordinate 


Returns: 


void 
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6.6.2.15 void gtk_paint_layout (GtkStyle x style, GdkWindow « window, GtkStateType state_type, 
gboolean use_text, GdkRectangle * area, GtkWidget « widget, const gchar « detail, gint x, 
gint y, PangoLayout x layout) 


Draws a layout on window using the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
use_text [in] whether to use the text or foreground graphics context of style 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin 
y [in] y origin 
layout [in] the layout to draw 


Returns: 


void 


6.6.2.16 void gtk_paint_option (GtkStyle x style, GdkWindow * window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle « area, GtkWidget « widget, const gchar x 
detail, gint x, gint y, gint width, gint height) 


Draws a radio button indicator in the given rectangle on window with the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the rectangle to draw the option in 
y [in] y origin of the rectangle to draw the option in 
width [in] the width of the rectangle to draw the option in 
height [in] the height of the rectangle to draw the option in 


Returns: 


void 
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6.6.2.17 void gtk_paint_polygon (GtkStyle « style, GdkWindow * window, GtkStateType 
state_type, GtkShadowType shadow_type, GdkRectangle x area, Gtk Widget * widget, const 
gchar x detail, GdkPoint x points, gint npoints, gboolean fill) 


Draws a polygon on window with the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
points [in] an array of GdkPoints 
npoints [in] length of points 
fill [in] TRUE if the polygon should be filled 


Returns: 


void 


6.6.2.18 void gtk_paint_resize_grip (GtkStyle x style, GdkWindow « window, GtkStateType 
state_type, GdkRectangle « area, GtkWidget x widget, const gchar + detail, 
GdkWindowEdge edge, gint x, gint y, gint width, gint height) 


Draws a resize grip in the given rectangle on window using the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
edge [in] the edge in which to draw the resize grip 
x [in] the x origin of the rectangle in which to draw the resize grip 
y [in] the y origin of the rectangle in which to draw the resize grip 
width [in] the width of the rectangle in which to draw the resize grip 


height [in] the height of the rectangle in which to draw the resize grip 


Returns: 


void 
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6.6.2.19 void gtk_paint_shadow (GtkStyle x style, GdkWindow x window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle x area, GtkWidget « widget, const gchar x 
detail, gint x, gint y, gint width, gint height) 


Draws a shadow around the given rectangle in window using the given style and state and shadow type. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the rectangle 
y [in] y origin of the rectangle 
width [in] width of the rectangle 
height [in] height of the rectangle 


Returns: 


void 


6.6.2.20 void gtk_paint_shadow_gap (GtkStyle x style, GdkWindow « window, GtkStateType 
state_type, GtkShadowType shadow_type, GdkRectangle x area, GtkWidget * widget, 
gchar x detail, gint x, gint y, gint width, gint height, GtkPositionType gap_side, gint gap_x, 
gint gap_width) 


Draws a shadow around the given rectangle in window using the given style and state and shadow type, 
leaving a gap in one side. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] x origin of the extension 
y [in] y origin of the extension 
width [in] width of the extension 
height [in] height of the extension 
gap_side [in] side in which to leave the gap 
gap_x [in] starting position of the gap 
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gap_width [in] width of the gap 


Returns: 


void 


6.6.2.21 void gtk_paint_slider (GtkStyle « style, GdkWindow x window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle « area, GtkWidget « widget, const gchar x 
detail, gint x, gint y, gint width, gint height, GtkOrientation orientation) 


Draws a handle as used in GtkHandleBox and GtkPaned. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] a shadow 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
x [in] the x origin of the rectangle in which to draw a slider 
y [in] the y origin of the rectangle in which to draw a slider 
width [in] the width of the rectangle in which to draw a slider 
height [in] the height of the rectangle in which to draw a slider 


orientation [in] the orientation to be used 


Returns: 


void 


6.6.2.22 void gtk_paint_tab (GtkStyle x style, GdkWindow x window, GtkStateType state_type, 
GtkShadowType shadow_type, GdkRectangle « area, GtkWidget « widget, const gchar x 
detail, gint x, gint y, gint width, gint height) 


Draws an option menu tab (i.e. 


the up and down pointing arrows) in the given rectangle on window using the given parameters. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 
shadow_type [in] type of shadow to draw 
area [in] clip rectangle, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 
detail [in] a style detail (may be NULL) 
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x [in] x origin of the rectangle to draw the tab in 

y [in] y origin of the rectangle to draw the tab in 

width [in] the width of the rectangle to draw the tab in 
height [in] the height of the rectangle to draw the tab in 


Returns: 


void 


6.6.2.23 void gtk_paint_vline (GtkStyle x style, GdkWindow « window, GtkStateType state_type, 
GdkRectangle x area, GtkWidget * widget, const gchar « detail, gint y1_, gint y2_, gint x) 


Draws a vertical line from (x, y1_) to (x, y2_) in window using the given style and state. 


Parameters: 


style [in] a GtkStyle 

window [in] a GdkWindow 

state_type [in] a state 

area [in] rectangle to which the output is clipped, or NULL if the output should not be clipped 
widget [in] the widget (may be NULL) 

detail [in] a style detail (may be NULL) 

y1_ [in] the starting y coordinate 

y2_ [in] the ending y coordinate 

x [in] the x coordinate 


Returns: 


void 


6.6.2.24 void gtk_style_apply_default_background (GtkStyle x style, Gdk Window * window, 
gboolean set_bg, GtkStateType state_type, GdkRectangle x area, gint x, gint y, gint width, 
gint height) 


Sets the background of window to the background color using the given parameters. 


Parameters: 


style [in] a GtkStyle 

window [in] a GdkWindow 

set_bg [in] TRUE to set the Back ground 
state_type [in] a state 

area [in] clip rectangle 

x [in] x origin of the rectangle 

y [in] y origin of the rectangle 

width [in] width of the rectangle 

height [in] height of the rectangle 


Returns: 


void 
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6.6.2.25  GtkStylex gtk_style_attach (GtkStyle x style, GdkWindow * window) 
Attaches a style to a window; this process allocates the colors and creates the GC’s for the style - it 
specializes it to a particular visual and colormap. 


The process may involve the creation of a new style if the style has already been attached to a window with 
a different style and colormap. 


Since this function may return a new object, you have to use it in the following way: style = gtk_style_- 
attach (style, window) 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
Returns: 


Either style, or a newly-created GtkStyle. If the style is newly created, the style parameter will be 
unref”ed, and the new style will have a reference count belonging to the caller. 


6.6.2.26 GtkStylex gtk_style_copy (GtkStyle « style) 
Copies a GtkStyle structure. 


Parameters: 


style [in] a GtkStyle 


Returns: 


a copy GtkStyle 


6.6.2.27 void gtk_style_detach (GtkStyle x style) 


Detaches a style from a window. 


If the style is not attached to any windows anymore, it is unrealized. See gtk_style_attach(). 


Parameters: 


style [in] a GtkStyle 


Returns: 


void 


6.6.2.28 gboolean gtk_style_lookup_color (GtkStyle x style, const gchar « color_name, GdkColor = 
color) 


Looks up color_name in the style’s logical color mappings, filling in color and returning TRUE if found, 
otherwise returning FALSE. 


Do not cache the found mapping, because it depends on the GtkStyle and might change when a theme 
switch occurs. 
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Parameters: 


style [in] a GtkStyle 
color_name [in] the name of the logical color to look up 
color [in] the GdkColor to fill in 


Returns: 


TRUE if the mapping was found. 


6.6.2.29 GtkIconSet« gtk_style_lookup_icon_set (GtkStyle x style, const gchar * stock_id) 


fn : gtk_style_lookup_icon_set 


Parameters: 
style [in] a GtkStyle 
stock_id [in] stock id 
Returns: 


a GtkIconSet 


6.6.2.30  GtkStylex gtk_style_new (void) 


Creates a new GtkStyle. 


Returns: 


a new GtkStyle. 


6.6.2.31 GdkPixbufx gtk_style_render_icon (GtkStyle x style, const GtkIconSource x source, 
GtkTextDirection direction, GtkStateType state, GtkIconSize size, GtkWidget * widget, 
const gchar * detail) 


Renders the icon specified by source at the given size according to the given parameters and returns the 
result in a pixbuf. 


Parameters: 
style [in] a GtkStyle 
source [in] the GtkIconSource specifying the icon to render 
direction [in] a text direction 
state [in] a state 


size [in] the size to render the icon at. A size of (GtkIconSize)-1 means render at the size of the source 
and don’t scale. 


widget [in] the widget 
detail [in] a style detail 
Returns: 


a newly-created GdkPixbuf containing the rendered icon 
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6.6.2.32 void gtk_style_set_background (GtkStyle x style, GdkWindow x window, GtkStateType 
state_type) 


Sets the background of window to the background color or pixmap specified by style for the given state. 


Parameters: 
style [in] a GtkStyle 
window [in] a GdkWindow 
state_type [in] a state 


Returns: 


void 
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6.7 I18N 


6.7.1 Detailed Description 


Provides 118n conversion APIs. 


Defines 


e #define P_(String) (String) 
Provides i18n String. 


e #define I_(string) g_intern_static_string (string) 


not really 118N-related, but also a string marker macro 


6.7.2 Define Documentation 
6.7.2.1 #define I_(string) g_intern_static_string (string) 


not really 118N-related, but also a string marker macro 


6.7.2.2 #define P_(String) (String) 


Provides 118n String. 
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6.8 GtkIconFactory 


6.8.1 Detailed Description 


An icon factory manages a collection of GtkIconSet; a GtkIconSet manages a set of variants of a particular 
icon (i.e. 


a GtkIconSet contains variants for different sizes and widget states). Icons in an icon factory are named by 
a stock ID, which is a simple string identifying the icon. 


Each GtkStyle has a list of GtkIconFactory derived from the current theme; those icon factories are con- 
sulted first when searching for an icon. If the theme doesn’t set a particular icon, GTK+ looks for the icon 
in a list of default icon factories, maintained by gtk_icon_factory_add_default() and gtk_icon_factory_- 
remove_default(). Applications with icons should add a default icon factory with their icons, which will 
allow themes to override the icons for the application. 


To display an icon, always use gtk_style_lookup_icon_set() on the widget that will display the icon, or 
the convenience function gtk_widget_render_icon(). These functions take the theme into account when 
looking up the icon to use for a given stock ID. 


Data Structures 


e struct _GtkIconFactory 


GtkIconFactory instance structure. 


e struct _GtkIconFactoryClass 


GtkIconFactory instance class structure. 


Functions 


e GtkIconFactory x gtk_icon_factory_new (void) 


Creates a new GtkIconFactory. 


e void gtk_icon_factory_add (GtkIconFactory xfactory, const gchar *stock_id, GtkIconSet *icon_- 
set) 


Adds the given icon_set to the icon factory, under the name stock_id. 


e GtkIconSet x gtk_icon_factory_lookup (GtkIconFactory *factory, const gchar «stock_id) 


Looks up stock_id in the icon factory, returning an icon set if found, otherwise NULL. 


e void gtk_icon_factory_add_default (GtkIconFactory factory) 


Adds an icon factory to the list of icon factories searched by gtk_style_lookup_icon_set(). 


e void gtk_icon_factory_remove_default (GtkIconFactory *factory) 


Removes an icon factory from the list of default icon factories. 


e GtkIconSet * gtk_icon_factory_lookup_default (const gchar *stock_id) 


Looks for an icon in the list of default icon factories. 


e gboolean gtk_icon_size_lookup (GtkIconSize size, gint «width, gint xheight) 
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Obtains the pixel size of a semantic icon size, possibly modified by user preferences for the default GtkSet- 
tings. 


gboolean gtk_icon_size_lookup_for_settings (GtkSettings «settings, GtkIconSize size, gint «width, 
gint xheight) 


Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular GtkSet- 
tings. 


GtkIconSize gtk_icon_size_register (const gchar xname, gint width, gint height) 


Registers a new icon size, along the same lines as GTK_ICON_SIZE_MENU, etc. 


void gtk_icon_size_register_alias (const gchar *alias, GtkIconSize target) 


Registers alias as another name for target. 


GtkIconSize gtk_icon_size_from_name (const gchar xname) 


Looks up the icon size associated with name. 


G_CONST_RETURN gchar x gtk_icon_size_get_name (GtkIconSize size) 


Gets the canonical name of the given icon size. 


GtkIconSet * gtk_icon_set_new (void) 


Creates a new GtkIconSet. 


GtkIconSet * gtk_icon_set_new_from_pixbuf (GdkPixbuf *pixbuf) 


Creates a new GtkIconSet with pixbuf as the default/fallback source image. 


GtkIconSet x gtk_icon_set_ref (GtkIconSet *icon_set) 


Increments the reference count on icon_set. 


void gtk_icon_set_unref (GtkIconSet *icon_set) 


Decrements the reference count on icon_set, and frees memory if the reference count reaches 0. 


GtkIconSet * gtk_icon_set_copy (GtkIconSet x*icon_set) 


Copies icon_set by value. 


GdkPixbuf x gtk_icon_set_render_icon (GtkIconSet *icon_set, GtkStyle «style, GtkTextDirection 
direction, GtkStateType state, GtkIconSize size, GtkWidget «widget, const char +detail) 


Renders an icon using gtk_style_render_icon(). 


void gtk_icon_set_add_source (GtkIconSet *icon_set, const GtkIconSource *source) 


Icon sets have a list of GtkIconSource, which they use as base icons for rendering icons in different states 
and sizes. 


void gtk_icon_set_get_sizes (GtkIconSet *icon_set, GtkIconSize «*sizes, gint *n_sizes) 


Obtains a list of icon sizes this icon set can render. 


GtkIconSource * gtk_icon_source_new (void) 


Creates a new GtkIconSource. 


GtkIconSource * gtk_icon_source_copy (const GtkIconSource *source) 
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Creates a copy of source; mostly useful for language bindings. 


e void gtk_icon_source_free (GtkIconSource *source) 


Frees a dynamically-allocated icon source, along with its filename, size, and pixbuf fields if those are not 
NULL. 


e void gtk_icon_source_set_filename (GtkIconSource *source, const gchar *filename) 


Sets the name of an image file to use as a base image when creating icon variants for GtkIconSet. 


e void gtk_icon_source_set_icon_name (GtkIconSource «source, const gchar *icon_name) 


Sets the name of an icon to look up in the current icon theme to use as a base image when creating icon 
variants for GtkIconSet. 


e void gtk_icon_source_set_pixbuf (GtkIconSource «source, GdkPixbuf *pixbuf) 


Sets a pixbuf to use as a base image when creating icon variants for GtkIconSet. 


e G_CONST_RETURN gchar * gtk_icon_source_get_filename (const GtkIconSource *source) 


Retrieves the source filename, or NULL if none is set. 


e G_CONST_RETURN gchar x gtk_icon_source_get_icon_name (const GtkIconSource *source) 


Retrieves the source icon name, or NULL if none is set. 


e GdkPixbuf x gtk_icon_source_get_pixbuf (const GtkIconSource *source) 


Retrieves the source pixbuf, or NULL if none is set. 


e void gtk_icon_source_set_direction_wildcarded (GtkIconSource «source, gboolean setting) 


If the text direction is wildcarded, this source can be used as the base image for an icon in any GtkTextDi- 
rection. 


e void gtk_icon_source_set_state_wildcarded (GtkIconSource *source, gboolean setting) 


Sets the widget state this icon source is intended to be used with. 


e void gtk_icon_source_set_size_wildcarded (GtkIconSource *source, gboolean setting) 


If the icon size is wildcarded, this source can be used as the base image for an icon of any size. 


e gboolean gtk_icon_source_get_size_wildcarded (const GtkIconSource *source) 


Gets the value set by gtk_icon_source_set_size_wildcarded(). 


e gboolean gtk_icon_source_get_state_wildcarded (const GtkIconSource *source) 


Gets the value set by gtk_icon_source_set_state_wildcarded(). 


e gboolean gtk_icon_source_get_direction_wildcarded (const GtkIconSource *source) 


Gets the value set by gtk_icon_source_set_direction_wildcarded(). 


e void gtk_icon_source_set_direction (GtkIconSource «source, GtkTextDirection direction) 


Sets the text direction this icon source is intended to be used with. 


e void gtk_icon_source_set_state (GtkIconSource «source, GtkStateType state) 


Sets the widget state this icon source is intended to be used with. 
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e void gtk_icon_source_set_size (GtkIconSource *source, GtkIconSize size) 


Sets the icon size this icon source is intended to be used with. 


GtkTextDirection gtk_icon_source_get_direction (const GtkIconSource *source) 


Obtains the text direction this icon source applies to. 


GtkStateType gtk_icon_source_get_state (const GtkIconSource *source) 


Obtains the widget state this icon source applies to. 


e GtkIconSize gtk_icon_source_get_size (const GtkIconSource *source) 


Obtains the icon size this source applies to. 


6.8.2 Function Documentation 


6.8.2.1 void gtk_icon factory_add (GtkIconFactory * factory, const gchar x stock_id, GtkIconSet x 
icon_set) 


Adds the given icon_set to the icon factory, under the name stock_id. 


stock_id should be namespaced for your application, e.g. "myapp-whatever-icon". Normally applications 
create a GtkIconFactory, then add it to the list of default factories with gtk_icon_factory_add_default(). 
Then they pass the stock_id to widgets such as GtkImage to display the icon. Themes can provide an icon 
with the same name (such as "myapp-whatever-icon") to override your application’s default icons. If an 
icon already existed in factory for stock_id, it is unreferenced and replaced with the new icon_set. 


Parameters: 


factory [in] a GtkIconFactory 
stock_id [in] icon name 


icon_set [in] icon set 


Returns: 


void 


6.8.2.2 void gtk_icon_factory_add_default (GtkIconFactory x factory) 


Adds an icon factory to the list of icon factories searched by gtk_style_lookup_icon_set(). 


This means that, for example, gtk_image_new_from_stock() will be able to find icons in factory. There 
will normally be an icon factory added for each library or application that comes with icons. The default 
icon factories can be overridden by themes. 


Parameters: 


factory [in] a GtkIconFactory 


Returns: 


void 
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6.8.2.3 GtkIconSetx gtk_icon_factory_lookup (GtkIconFactory * factory, const gchar x stock_id) 


Looks up stock_id in the icon factory, returning an icon set if found, otherwise NULL. 


For display to the user, you should use gtk_style_lookup_icon_set() on the GtkStyle for the widget that 
will display the icon, instead of using this function directly, so that themes are taken into account. 


Parameters: 
factory [in] a GtkIconFactory 


stock_id [in] an icon name 


Returns: 


icon set of stock_id. 


6.8.2.4 GtkIconSetx gtk_icon_factory_lookup_default (const gchar x stock_id) 


Looks for an icon in the list of default icon factories. 


For display to the user, you should use gtk_style_lookup_icon_set() on the GtkStyle for the widget that 
will display the icon, instead of using this function directly, so that themes are taken into account 


Parameters: 


stock_id [in] an icon name 


Returns: 


a GtkIconSet, or NULL 


6.8.2.5 GtkIconFactoryx gtk_icon_factory_new (void) 


Creates a new GtkIconFactory. 


An icon factory manages a collection of GtkIconSets; a GtkIconSet manages a set of variants of a particu- 
lar icon (i.e. a GtkIconSet contains variants for different sizes and widget states). Icons in an icon factory 
are named by a stock ID, which is a simple string identifying the icon. Each GtkStyle has a list of GtkI- 
conFactorys derived from the current theme; those icon factories are consulted first when searching for an 
icon. If the theme doesn’t set a particular icon, GTK+ looks for the icon in a list of default icon factories, 
maintained by gtk_icon_factory_add_default() and gtk_icon_factory_remove_default(). Applications with 
icons should add a default icon factory with their icons, which will allow themes to override the icons for 
the application. 


Returns: 


a new GtkIconFactory 


6.8.2.6 void gtk_icon_factory_remove_default (GtkIconFactory * factory) 


Removes an icon factory from the list of default icon factories. 


Not normally used; you might use it for a library that can be unloaded or shut down. 
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Parameters: 


factory [in] a GtkIconFactory 


Returns: 


void 


6.8.2.7 void gtk_icon_set_add_source (GtkIconSet x icon_set, const GtkIconSource x source) 


Icon sets have a list of GtkIconSource, which they use as base icons for rendering icons in different states 
and sizes. 


Icons are scaled, made to look insensitive, etc. in gtk_icon_set_render_icon(), but GtkIconSet needs base 
images to work with. The base images and when to use them are described by a GtkIconSource. This 
function copies source, so you can reuse the same source immediately without affecting the icon set. An 
example of when you’d use this function: a web browser’s "Back to Previous Page" icon might point in a 
different direction in Hebrew and in English; it might look different when insensitive; and it might change 
size depending on toolbar mode (small/large icons). So a single icon set would contain all those variants 
of the icon, and you might add a separate source for each one. You should nearly always add a "default" 
icon source with all fields wildcarded, which will be used as a fallback if no more specific source matches. 
GtkIconSet always prefers more specific icon sources to more generic icon sources. The order in which 
you add the sources to the icon set does not matter. gtk_icon_set_new_from_pixbuf() creates a new icon 
set with a default icon source based on the given pixbuf. 


Parameters: 


icon_set [in] a GtkIconSet 


source [in] a GtkIconSource 


Returns: 


void 


6.8.2.8 GtkIconSet* gtk_icon_set_copy (GtkIconSet x icon_set) 
Copies icon_set by value. 


Parameters: 


icon_set [in] a GtkIconSet 


Returns: 


a new GtkIconSet identical to the first. 


6.8.2.9 void gtk_icon_set_get_sizes (GtkIconSet x icon_set, GtkIconSize x» sizes, gint « n_sizes) 


Obtains a list of icon sizes this icon set can render. 


The returned array must be freed with g_free(). 


Parameters: 


name [in] name of the icon size 
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> sizes [in] return location for array of sizes 


— n_sizes [in] location to store number of elements in returned array 


Returns: 


void 


6.8.2.10  GtkIconSetx gtk_icon_set_new (void) 


Creates a new GtkIconSet. 


A GtkIconSet represents a single icon in various sizes and widget states. It can provide a GdkPixbuf 
for a given size and state on request, and automatically caches some of the rendered GdkPixbuf objects. 
Normally you would use gtk_widget_render_icon() instead of using GtkIconSet directly. The one case 
where you'd use GtkIconSet is to create application-specific icon sets to place in a GtkIconFactory 


Returns: 


a new GtkIconSet 


6.8.2.11 GtkIconSet« gtk_icon_set_new_from_pixbuf (GdkPixbuf x pixbuf) 


Creates a new GtkIconSet with pixbuf as the default/fallback source image. 


If you don’t add any additional GtkIconSource to the icon set, all variants of the icon will be created 
from pixbuf, using scaling, pixelation, etc. as required to adjust the icon size or make the icon look 
insensitive/prelighted. 


Parameters: 


pixbuf [in] a GdkPixbuf 


Returns: 


a new GtkIconSet 


6.8.2.12 GtkIconSet« gtk_icon_set_ref (GtkIconSet x icon_set) 


Increments the reference count on icon_set. 


Parameters: 


icon_set [in] a GtkIconSet 


Returns: 


icon_set. 
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6.8.2.13 GdkPixbuf« gtk_icon_set_render_icon (GtkIconSet x icon_set, GtkStyle x style, 
GtkTextDirection direction, GtkStateType state, GtkIconSize size, Gtk Widget « widget, 
const char x detail) 


Renders an icon using gtk_style_render_icon(). 


In most cases, gtk_widget_render_icon() is better, since it automatically provides most of the arguments 
from the current widget settings. This function never returns NULL; if the icon can’t be rendered (perhaps 
because an image file fails to load), a default "missing image" icon will be returned instead. 


Parameters: 
icon_set [in] a GtkIconSet 
style [in] a GtkStyle associated with widget, or NULL 
direction [in] text direction 
state [in] widget state 
size [in] icon size. A size of (GtkIconSize)-1 means render at the size of the source and don’t scale. 


widget [in] widget that will display the icon, or NULL. The only use that is typically made of this is 
to determine the appropriate GdkScreen. 


detail [in] detail to pass to the theme engine, or NULL. Note that passing a detail of anything but 
NULL will disable caching. 


Returns: 


a GdkPixbuf to be displayed 


6.8.2.14 void gtk_icon_set_unref (GtkIconSet « icon_set) 


Decrements the reference count on icon_set, and frees memory if the reference count reaches 0. 


Parameters: 


icon_set [in] a GtkIconSet 


Returns: 


void 


6.8.2.15 GtkIconSize gtk_icon_size_from_name (const gchar x name) 


Looks up the icon size associated with name. 


Parameters: 


name [in] the name to look up. 


Returns: 


the icon size with the given name. 
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6.8.2.16 G_CONST_RETURN gchar» gtk_icon_size_get_name (GtkIconSize size) 


Gets the canonical name of the given icon size. 
The returned string is statically allocated and should not be freed. 
Parameters: 


size [in] name of the icon size 


Returns: 


the name of the given icon size. 


6.8.2.17 gboolean gtk_icon_size_lookup (GtkIconSize size, gint x width, gint x height) 


Obtains the pixel size of a semantic icon size, possibly modified by user preferences for the default Gtk- 
Settings. 


(See gtk_icon_size_lookup_for_settings().) Normally size would be GTK_ICON_SIZE_MENU, GTK_- 
ICON_SIZE_BUTTON, etc. This function isn’t normally needed, gtk_widget_render_icon() is the usual 
way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf 
may not even correspond to the width/height returned by gtk_icon_size_lookup(), because themes are free 
to render the pixbuf however they like, including changing the usual size. 


Parameters: 


factory [in] a GtkIconFactory 
width [out] location to store icon width 
height [out] location to store icon height 


Returns: 


TRUE if size was a valid size 


6.8.2.18 gboolean gtk_icon_size_lookup_for_settings (GtkSettings x settings, GtkIconSize size, gint 
x width, gint x height) 


Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular Gtk- 
Settings. 


Normally size would be GTK_ICON_SIZE_MENU, GTK_ICON_SIZE_BUTTON, etc. This function 
isn’t normally needed, gtk_widget_render_icon() is the usual way to get an icon for rendering, then just 
look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height 
returned by gtk_icon_size_lookup(), because themes are free to render the pixbuf however they like, in- 
cluding changing the usual size. 


Parameters: 


settings [in] a GtkSettings object, used to determine which set of user preferences to used. 
size [in] an icon size 

width [out] location to store icon width 

height [out] location to store icon height 


Returns: 


TRUE if size was a valid size 
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6.8.2.19 GtkIconSize gtk_icon_size_register (const gchar x name, gint width, gint height) 
Registers a new icon size, along the same lines as GTK_ICON_SIZE_MENU, etc. 
Returns the integer value for the size. 


Parameters: 


name [in] name of the icon size 
width [out] the icon width 
height [out] the icon width 


Returns: 


integer value representing the size 


6.8.2.20 void gtk_icon_size_register_alias (const gchar x alias, GtkIconSize target) 


Registers alias as another name for target. 


So calling gtk_icon_size_from_name() with alias as argument will return target. 


Parameters: 


alias [in] an alias for target 


target [out] an existing icon size 


Returns: 


void 


6.8.2.21 GtkIconSourcex gtk_icon_source_copy (const GtkIconSource * source) 


Creates a copy of source; mostly useful for language bindings. 


Parameters: 


source [in] a GtklconSource 


Returns: 


a new GtkIconSource 


6.8.2.22 void gtk_icon_source_free (GtkIconSource x source) 


Frees a dynamically-allocated icon source, along with its filename, size, and pixbuf fields if those are not 
NULL. 


Parameters: 


source [in] a GtklconSource 


Returns: 


void 
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6.8.2.23 GtkTextDirection gtk_icon_source_get_direction (const GtkIconSource * source) 


Obtains the text direction this icon source applies to. 


The return value is only useful/meaningful if the text direction is not wildcarded. 


Parameters: 


source [in] a GtklconSource 


Returns: 


text direction this source matches 


6.8.2.24 gboolean gtk_icon_source_get_direction_wildcarded (const GtkIconSource x source) 


Gets the value set by gtk_icon_source_set_direction_wildcarded(). 


Parameters: 


source [in] a GtkIconSource 


Returns: 


TRUE if this icon source is a base for any text direction variant 


6.8.2.25 G_CONST_RETURN gchar» gtk_icon_source_get_filename (const GtkIconSource + 
source) 


Retrieves the source filename, or NULL if none is set. 


The filename is not a copy, and should not be modified or expected to persist beyond the lifetime of the 
icon source. 


Parameters: 


source [in] a GtkIconSource 


Returns: 


image filename. This string must not be modified or freed. 


6.8.2.26 G_CONST_RETURN gchar» gtk_icon_source_get_icon_name (const GtkIconSource « 
source) 


Retrieves the source icon name, or NULL if none is set. 


The icon_name is not a copy, and should not be modified or expected to persist beyond the lifetime of the 
icon source. 


Parameters: 
source [in] a GtklconSource 
Returns: 


icon name. This string must not be modified or freed. 
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6.8.2.27 GdkPixbufx gtk_icon_source_get_pixbuf (const GtkIconSource x source) 


Retrieves the source pixbuf, or NULL if none is set. 


In addition, if a filename source is in use, this function in some cases will return the pixbuf from loaded 
from the filename. This is, for example, true for the GtkIconSource passed to the GtkStyle::render_icon() 
virtual function. The reference count on the pixbuf is not incremented. 


Parameters: 


source [in] a GtklconSource 


Returns: 


source pixbuf 


6.8.2.28 GtkIconSize gtk_icon_source_get_size (const GtkIconSource x source) 


Obtains the icon size this source applies to. 


The return value is only useful/meaningful if the icon size is not wildcarded. 


Parameters: 


source [in] a GtklconSource 


Returns: 


icon size this source matches. 


6.8.2.29 gboolean gtk_icon_source_get_size_wildcarded (const GtkIconSource * source) 


Gets the value set by gtk_icon_source_set_size_wildcarded(). 


Parameters: 


source [in] a GtklconSource 


Returns: 


TRUE if this icon source is a base for any icon size variant 


6.8.2.30 GtkStateType gtk_icon_source_get_state (const GtkIconSource x source) 


Obtains the widget state this icon source applies to. 


The return value is only useful/meaningful if the widget state is not wildcarded. 


Parameters: 


source [in] a GtklconSource 


Returns: 


widget state this source matches 
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6.8.2.31 gboolean gtk_icon_source_get_state_wildcarded (const GtkIconSource * source) 


Gets the value set by gtk_icon_source_set_state_wildcarded(). 


Parameters: 


source [in] a GtklconSource 


Returns: 


TRUE if this icon source is a base for any widget state variant 


6.8.2.32 GtkIconSourcex gtk_icon_source_new (void) 


Creates a new GtkIconSource. 


A GtkIconSource contains a GdkPixbuf (or image filename) that serves as the base image for one or more 
of the icons in a GtkIconSet, along with a specification for which icons in the icon set will be based on 
that pixbuf or image file. An icon set contains a set of icons that represent "the same" logical concept in 
different states, different global text directions, and different sizes. So for example a web browser’s "Back 
to Previous Page" icon might point in a different direction in Hebrew and in English; it might look different 
when insensitive; and it might change size depending on toolbar mode (small/large icons). So a single icon 
set would contain all those variants of the icon. GtkIconSet contains a list of GtkIconSource from which 
it can derive specific icon variants in the set. In the simplest case, GtkIconSet contains one source pixbuf 
from which it derives all variants. The convenience function gtk_icon_set_new_from_pixbuf() handles this 
case; if you only have one source pixbuf, just use that function. If you want to use a different base pixbuf 
for different icon variants, you create multiple icon sources, mark which variants they’ Il be used to create, 
and add them to the icon set with gtk_icon_set_add_source(). By default, the icon source has all parameters 
wildcarded. That is, the icon source will be used as the base icon for any desired text direction, widget 
state, or icon size. 


Returns: 


a new GtkIconSource 


6.8.2.33 void gtk_icon_source_set_direction (GtkIconSource « source, GtkTextDirection direction) 


Sets the text direction this icon source is intended to be used with. 


Setting the text direction on an icon source makes no difference if the text direction is wildcarded. There- 
fore, you should usually call gtk_icon_source_set_direction_wildcarded() to un-wildcard it in addition to 
calling this function. 


Parameters: 
source [in] a GtkIconSource 


direction [in] text direction this source applies to 


Returns: 


void 
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6.8.2.34 void gtk_icon_source_set_direction_wildcarded (GtkIconSource * source, gboolean 
setting) 


If the text direction is wildcarded, this source can be used as the base image for an icon in any GtkTextDi- 
rection. 


Tf the text direction is not wildcarded, then the text direction the icon source applies to should be set with 
gtk_icon_source_set_direction(), and the icon source will only be used with that text direction. GtkIconSet 
prefers non-wildcarded sources (exact matches) over wildcarded sources, and will use an exact match when 
possible. 


Parameters: 


source [in] a GtklconSource 


setting [in] TRUE to wildcard the text direction 


Returns: 


void 


6.8.2.35 void gtk_icon_source_set_filename (GtkIconSource x source, const gchar x filename) 


Sets the name of an image file to use as a base image when creating icon variants for GtkIconSet. 


The filename must be absolute. 


Parameters: 


source [in] a GtklconSource 


filename [in] image file to use 


Returns: 


void 


6.8.2.36 void gtk_icon_source_set_icon_name (GtkIconSource x source, const gchar x icon_name) 


Sets the name of an icon to look up in the current icon theme to use as a base image when creating icon 
variants for GtkIconSet. 


Parameters: 


source [in] a GtklconSource 


icon_name [in] name of icon to use 


Returns: 


void 


6.8.2.37 void gtk_icon_source_set_pixbuf (GtkIconSource x source, GdkPixbuf x pixbuf) 


Sets a pixbuf to use as a base image when creating icon variants for GtkIconSet. 
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Parameters: 
source [in] a GtklconSource 


pixbuf [in] pixbuf to use as a source 


Returns: 


void 


6.8.2.38 void gtk_icon_source_set_size (GtkIconSource x source, GtkIconSize size) 


Sets the icon size this icon source is intended to be used with. 


Setting the icon size on an icon source makes no difference if the size is wildcarded. Therefore, you 
should usually call gtk_icon_source_set_size_wildcarded() to un-wildcard it in addition to calling this 
function. 


Parameters: 
source [in] a GtklconSource 


size [in] icon size this source applies to 


Returns: 


void 


6.8.2.39 void gtk_icon_source_set_size_wildcarded (GtkIconSource « source, gboolean setting) 


If the icon size is wildcarded, this source can be used as the base image for an icon of any size. 


If the size is not wildcarded, then the size the source applies to should be set with gtk_icon_source_set_- 
size() and the icon source will only be used with that specific size. GtkIconSet prefers non-wildcarded 
sources (exact matches) over wildcarded sources, and will use an exact match when possible. GtkIconSet 
will normally scale wildcarded source images to produce an appropriate icon at a given size, but will not 
change the size of source images that match exactly. 


Parameters: 
source [in] a GtkIconSource 


setting [in] TRUE to wildcard the widget state 


Returns: 


void 


6.8.2.40 void gtk_icon_source_set_state (GtkIconSource x source, GtkStateType state) 


Sets the widget state this icon source is intended to be used with. 


Setting the widget state on an icon source makes no difference if the state is wildcarded. Therefore, you 
should usually call gtk_icon_source_set_state_wildcarded() to un-wildcard it in addition to calling this 
function. 
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Parameters: 


source [in] a GtklconSource 


state [in] widget state this source applies to 


Returns: 


void 


6.8.2.41 void gtk_icon_source_set_state_wildcarded (GtkIconSource x source, gboolean setting) 


Sets the widget state this icon source is intended to be used with. 


Setting the widget state on an icon source makes no difference if the state is wildcarded. Therefore, you 
should usually call gtk_icon_source_set_state_wildcarded() to un-wildcard it in addition to calling this 
function 


Parameters: 


source [in] a GtklconSource 


setting [in] widget state this source applies to 


Returns: 


void 
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6.9 GtkIconTheme 


6.9.1 Detailed Description 


GtkIconTheme provides a facility for looking up icons by name and size. 


The main reason for using a name rather than simply providing a filename is to allow different icons to 
be used depending on what icon theme is selecetd by the user. The operation of icon themes on Linux 
and Unix follows the Icon Theme Specification. There is a default icon theme, named hicolor where 
applications should install their icons, but more additional application themes can be installed as operating 
system vendors and users choose. 


Named icons are similar to the Themeable Stock Images(3) facility, and the distinction between the two 
may be a bit confusing. A few things to keep in mind: 


1. Stock images usually are used in conjunction with Stock Items(3)., such as GTK_STOCK_OK or 
GTK_STOCK_OPEN. Named icons are easier to set up and therefore are more useful for new icons that 
an application wants to add, such as application icons or window icons. 


2. Stock images can only be loaded at the symbolic sizes defined by the GtkIconSize enumeration, or by 
custom sizes defined by gtk_icon_size_register(), while named icons are more flexible and any pixel size 
can be specified. 


3. Because stock images are closely tied to stock items, and thus to actions in the user interface, stock 
images may come in multiple variants for different widget states or writing directions. 


A good rule of thumb is that if there is a stock image for what you want to use, use it, otherwise use a 
named icon. It turns out that internally stock images are generally defined in terms of one or more named 
icons. (An example of the more than one case is icons that depend on writing direction, GTK_STOCK_- 
GO_FORWARD uses the two themed icons "gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".) 


In many cases, named themes are used indirectly, via GtkImage or stock items, rather than directly, but 
looking up icons directly is also simple. The GtkIconTheme object acts as a database of all the icons in the 
current theme. You can create new GtkIconTheme objects, but its much more efficient to use the standard 
icon theme for the GdkScreen so that the icon information is shared with other people looking up icons. In 
the case where the default screen is being used, looking up an icon can be as simple as: 


GError xerror = NULL; 
GtkIconTheme *icon_theme; 
GdkPixbuf *pixbuf; 


icon_theme = gtk_icon_theme_get_default (); 

pixbuf = gtk_icon_theme_load_icon (icon_theme, 
"my-icon-name", // icon name 
48, // size 
0, // flags 
&error); 


if (!pixbuf) 
{ 
g_warning ("Couldn’t load icon: %s", error->message) ; 
g_error_free (error); 
} 
else 
{ 
// Use the pixbuf 
g_object_unref (pixbuf); 
) 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


90 


Module Documentation 


Data Structures 


e struct _GtkIconTheme 


GtkIconTheme instance structure. 


e struct _GtkIconThemeClass 


GtkIconTheme instance class structure. 


Enumerations 


e enum GtkIconLookupFlags 


GtkIconLookupFlags: : Never return SVG icons, even if gdk-pixbuf supports them. 


+ enum GtkIconThemeError 


GtkIconThemeError: : The icon specified does not exist in the theme : An unspecified error occurred. 


Functions 


GtkIconTheme x gtk_icon_theme_new (void) 


Creates a new icon theme object. 


GtkIconTheme * gtk_icon_theme_get_default (void) 


Gets the icon theme for the default screen. 


GtkIconTheme * gtk_icon_theme_get_for_screen (GdkScreen *screen) 


Gets the icon theme object associated with screen; if this function has not previously been called for the 
given screen, a new icon theme object will be created and associated with the screen. 


void gtk_icon_theme_set_screen (GtkIconTheme *icon_theme, GdkScreen *screen) 


Sets the screen for an icon theme; the screen is used to track the user’s currently configured icon theme, 
which might be different for different screens. 


void gtk_icon_theme_set_search_path (GtkIconTheme x*icon_theme, const gchar *path[ ], gint n_- 
elements) 


Sets the search path for the icon theme object. 


void gtk_icon_theme_get_search_path (GtkIconTheme *icon_theme, gchar **path[], gint *n_- 
elements) 


Gets the current search path. 


void gtk_icon_theme_append_search_path (GtkIconTheme x*icon_theme, const gchar xpath) 


Appends a directory to the search path. 


void gtk_icon_theme_prepend_search_path (GtkIconTheme *icon_theme, const gchar xpath) 


Prepends a directory to the search path. 


void gtk_icon_theme_set_custom_theme (GtkIconTheme *icon_theme, const gchar »*theme_- 
name) 
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Sets the screen for an icon theme; theSets the name of the icon theme that the GtkIconTheme object uses 
overriding system configuration. 


e gboolean gtk_icon_theme_has_icon (GtkIconTheme *icon_theme, const gchar *icon_name) 


Checks whether an icon theme includes an icon for a particular name. 


e gint x gtk_icon_theme_get_icon_sizes (GtklconTheme x*icon_theme, const gchar *icon_name) 


Returns an array of integers describing the sizes at which the icon is available without scaling. 


e GtkIconInfo * gtk_icon_theme_lookup_icon (GtkIconTheme x*icon_theme, const gchar *icon_- 
name, gint size, GtkIconLookupFlags flags) 


Looks up a named icon and returns a structure containing information such as the filename of the icon. 


e GdkPixbuf * gtk_icon theme _load_icon (GtkIconTheme *icon_theme, const gchar *icon_name, 
gint size, GtkIconLookupFlags flags, GError *xerror) 


Looks up an icon in an icon theme, scales it to the given size and renders it into a pixbuf. 


e GList * gtk_icon_theme_list_icons (GtkIconTheme x*icon_theme, const gchar *context) 


Lists the icons in the current icon theme. 


e char * gtk_icon_theme_get_example_icon_name (GtkIconTheme *icon_theme) 


Gets the name of an icon that is representative of the current theme (for instance, to use when presenting a 
list of themes to the user. 


e gboolean gtk_icon_theme_rescan_if_needed (GtkIconTheme *icon_theme) 


Checks to see if the icon theme has changed; if it has, any currently cached information is discarded and 
will be reloaded next time icon_theme is accessed. 


e void gtk_icon_theme_add_builtin_icon (const gchar xicon_name, gint size, GdkPixbuf *pixbuf) 


Registers a built-in icon for icon theme lookups. 


e GtkIconInfo * gtk_icon_info_copy (GtkIconInfo *icon_info) 
Make a copy of a GtkIconInfo. 


e void gtk_icon_info_free (GtkIconInfo *icon_info) 


Free a GtkIconInfo and associated information. 


e gint gtk_icon_info_get_base_size (GtkIconInfo *icon_info) 


Gets the base size for the icon. 


e G_CONST_RETURN gchar x gtk_icon_info_get_filename (GtkIconInfo *icon_info) 


Gets the filename for the icon. 


e GdkPixbuf x gtk_icon_info_get_builtin_pixbuf (GtkIconInfo *icon_info) 


Gets the built-in image for this icon, if any. 


e GdkPixbuf * gtk_icon_info_load_icon (GtkIconInfo *icon_info, GError *xerror) 


Renders an icon previously looked up in an icon theme using gtk_icon_theme_lookup_icon(); the size will 
be based on the size passed to gtk_icon_theme_lookup_icon(). 


e void gtk_icon_info_set_raw_coordinates (GtkIconInfo *icon_info, gboolean raw_coordinates) 
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Sets whether the coordinates returned by gtk_icon_info_get_embedded_rect() and gtk_icon_info_get_- 
attach_points() should be returned in their original form as specified in the icon theme, instead of scaled 
appropriately for the pixbuf returned by gtk_icon_info_load_icon(). 


e gboolean gtk_icon_info_get_embedded_rect (GtkIconInfo *icon_info, GdkRectangle *rectangle) 


Gets the coordinates of a rectangle within the icon that can be used for display of information such as a 
preview of the contents of a text file. 


e gboolean gtk_icon_info_get_attach_points (GtkIconInfo *icon_info, GdkPoint **points, gint *n_- 
points) 


Fetches the set of attach points for an icon. 


e G_CONST_RETURN gchar x gtk_icon_info_get_display_name (GtkIconInfo *icon_info) 


Gets the display name for an icon. 


6.9.2 Enumeration Type Documentation 
6.9.2.1 enum GtkIconLookupFlags 


GtkIconLookupFlags: : Never return SVG icons, even if gdk-pixbuf supports them. 


Cannot be used together with GTK_ICON_LOOKUP_FORCE_SVG. : Return SVG icons, even if gdk- 
pixbuf doesn’t support them. Cannot be used together with GTK_ICON_LOOKUP_NO_SVG. : When 
passed to gtk_icon_theme_lookup_icon() includes builtin icons as well as files. For a builtin icon, gtk_- 
icon_info_get_filename() returns NULL and you need to call gtk_icon_info_get_builtin_pixbuf(). 


Used to specify options for gtk_icon_theme_lookup_icon() 


6.9.2.2 enum GtkIconThemeError 


GtkIconThemeError: : The icon specified does not exist in the theme : An unspecified error occurred. 


Error codes for GtkIconTheme operations. 


6.9.3 Function Documentation 
6.9.3.1 GtkIconInfox gtk_icon_info_copy (GtkIconInfo x icon_info) 
Make a copy of a GtkIconInfo. 


Parameters: 


icon_info [in] a GtkIconInfo 


Returns: 


the new GtkIconInfo 


6.9.3.2 void gtk_icon_info_free (GtkIconInfo « icon_info) 


Free a GtkIconInfo and associated information. 
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Parameters: 


icon_info [in] a GtkIconInfo 


Returns: 


void 


6.9.3.3 gboolean gtk_icon_info_get_attach_points (GtkIconInfo x icon_info, GdkPoint xx points, 
gint x n_points) 


Fetches the set of attach points for an icon. 


An attach point is a location in the icon that can be used as anchor points for attaching emblems or overlays 
to the icon. 


Parameters: 
icon_info [in] a GtkIconInfo 


points [out] location to store pointer to an array of points, or NULL free the array of points with 
g_free(). 


n_points [out] location to store the number of points in points, or NULL 


Returns: 


TRUE if there are any attach points for the icon. 


6.9.3.4 gint gtk_icon_info_get_base_size (GtkIconInfo x icon_info) 


Gets the base size for the icon. 


The base size is a size for the icon that was specified by the icon theme creator. This may be different than 
the actual size of image; an example of this is small emblem icons that can be attached to a larger icon. 
These icons will be given the same base size as the larger icons to which they are attached. 


Parameters: 


icon_info [in] a GtkIconInfo 


Returns: 


the base size, or 0, if no base size is known for the icon. 


6.9.3.5 GdkPixbuf* gtk_icon_info_get_builtin_pixbuf (GtkIconInfo x icon_info) 


Gets the built-in image for this icon, if any. 


To allow GTK+ to use built in icon images, you must pass the GTK_ICON_LOOKUP_USE_BUILTIN to 
gtk_icon_theme_lookup_icon(). 


Parameters: 


icon_info [in] a GtkIconInfo structure 
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Returns: 


the built-in image pixbuf, or NULL. No extra reference is added to the returned pixbuf, so if you want 
to keep it around, you must use g_object_ref(). The returned image must not be modified. 


6.9.3.6  G_CONST_RETURN gcharx gtk_icon_info_get_display_name (GtkIconInfo x icon_info) 


Gets the display name for an icon. 


A display name is a string to be used in place of the icon name in a user visible context like a list of 
icons. 


Parameters: 


< icon_info [in] a GtkIconInfo 


Returns: 


the display name for the icon or NULL, if the icon doesn’t have a specified display name. This value 
is owned icon_info and must not be modified or free. 


6.9.3.7 gboolean gtk_icon_info_get_embedded_rect (GtkIconInfo x icon_info, GdkRectangle + 
rectangle) 


Gets the coordinates of a rectangle within the icon that can be used for display of information such as a 
preview of the contents of a text file. 


See gtk_icon_info_set_raw_coordinates() for further information about the coordinate system. 


Parameters: 
icon_info [in] a GtkIconInfo 
rectangle [in] GdkRectangle in which to store embedded rectangle coordinates; coordinates are only 
stored when this function returns TRUE. 
Returns: 


TRUE if the icon has an embedded rectangle 


6.9.3.8 G_CONST_RETURN gchar gtk_icon_info_get_filename (GtkIconInfo x icon_info) 


Gets the filename for the icon. 


If the GTK_ICON_LOOKUP_USE_BUILTIN flag was passed to gtk_icon_theme_lookup_icon(), there 
may be no filename if a builtin icon is returned; in this case, you should use gtk_icon_info_get_builtin_- 
pixbuf(). 


Parameters: 


icon_info [in] a GtkIconInfo 


Returns: 


the filename for the icon, or NULL if gtk_icon_info_get_builtin_pixbuf() should be used instead. The 
return value is owned by GTK+ and should not be modified or freed. 
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6.9.3.9 GdkPixbufx gtk_icon_info_load_icon (GtkIconInfo x icon_info, GError xx* error) 


Renders an icon previously looked up in an icon theme using gtk_icon_theme_lookup_icon(); the size will 
be based on the size passed to gtk_icon_theme_lookup_icon(). 


Note that the resulting pixbuf may not be exactly this size; an icon theme may have icons that differ slightly 
from their nominal sizes, and in addition GTK+ will avoid scaling icons that it considers sufficiently close 
to the requested size or for which the source image would have to be scaled up too far. (This maintains 
sharpness.) 


Parameters: 


icon_info [in] a GtkIconInfo structure from gtk_icon_theme_lookup_icon() 


error [out] location to store error information on failure, or NULL. 


Returns: 


the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must 
not modify the icon. Use g_object_unref() to release your reference to the icon. 


6.9.3.10 void gtk_icon_info_set_raw_coordinates (GtkIconInfo x icon_info, gboolean 
raw_coordinates) 


Sets whether the coordinates returned by gtk_icon_info_get_embedded_rect() and gtk_icon_info_get - 
attach_points() should be returned in their original form as specified in the icon theme, instead of scaled 
appropriately for the pixbuf returned by gtk_icon_info_load_icon(). 


Raw coordinates are somewhat strange; they are specified to be with respect to the unscaled pixmap for 
PNG and XPM icons, but for SVG icons, they are in a 1000x1000 coordinate space that is scaled to the 
final size of the icon. You can determine if the icon is an SVG icon by using gtk_icon_info_ get_filename(), 
and seeing if it is non-NULL and ends in ’.svg’. This function is provided primarily to allow compatibility 
wrappers for older API’s, and is not expected to be useful for applications. 


Parameters: 
icon_info [in] a GtkIconInfo 
raw_coordinates [in] whether the coordinates of embedded rectangles and attached points should be 
returned in their original (unscaled) form. 
Returns: 


void 


6.9.3.11 void gtk_icon_theme_add_builtin_icon (const gchar « icon_name, gint size, GdkPixbuf x 
pixbuf) 


Registers a built-in icon for icon theme lookups. 


The idea of built-in icons is to allow an application or library that uses themed icons to function requiring 
files to be present in the file system. For instance, the default images for all of GTK+’s stock icons are 
registered as built-icons. In general, if you use gtk_icon_theme_add_builtin_icon() you should also install 
the icon in the icon theme, so that the icon is generally available. This function will generally be used with 
pixbufs loaded via gdk_pixbuf_new_from_inline(). 
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Parameters: 


icon_theme [in] the name of the icon to register 


size [in] the size at which to register the icon (different images can be registered for the same icon 
name at different sizes.) 


pixbuf [in] GdkPixbuf that contains the image to use for icon_name. 


Returns: 


void 


6.9.3.12 void gtk_icon_theme_append_search_path (GtkIconTheme * icon_theme, const gchar x 
path) 


Appends a directory to the search path. 


See gtk_icon_theme_set_search_path(). 


Parameters: 

icon_theme [in] a GtkIconTheme 

path [in] directory name to append to the icon path 
Returns: 


void 


6.9.3.13 GtkIconTheme« gtk_icon_theme_get_default (void) 


Gets the icon theme for the default screen. 


See gtk_icon_theme_get_for_screen(). 


Parameters: 


bin [in] a GtkBin 


Returns: 


A unique GtkIconTheme associated with the default screen. This icon theme is associated with the 
screen and can be used as long as the screen is open. Do not ref or unref it. 


6.9.3.14 char» gtk_icon_theme_get_example_icon_name (GtkIconTheme + icon_theme) 


Gets the name of an icon that is representative of the current theme (for instance, to use when presenting a 
list of themes to the user. 


) 
Parameters: 

icon_theme [in] a GtkIconTheme 
Returns: 


the name of an example icon or NULL. Free with g_free(). 
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6.9.3.15 GtkIconThemex gtk_icon_theme_get_for_screen (GdkScreen x screen) 


Gets the icon theme object associated with screen; if this function has not previously been called for the 
given screen, a new icon theme object will be created and associated with the screen. 


Icon theme objects are fairly expensive to create, so using this function is usually a better choice than 
calling than gtk_icon_theme_new() and setting the screen yourself; by using this function a single icon 
theme object will be shared between users. 


Parameters: 


screen [in] a GdkScreen 


Returns: 


A unique GtkIconTheme associated with the given screen. This icon theme is associated with the 
screen and can be used as long as the screen is open. Do not ref or unref it. 


6.9.3.16 gint» gtk_icon_theme_get_icon_sizes (GtkIconTheme * icon_theme, const gchar + 
icon_name) 


Returns an array of integers describing the sizes at which the icon is available without scaling. 


A size of -1 means that the icon is available in a scalable format. The array is zero-terminated. 


Parameters: 
icon_theme [in] a GtkIconTheme 


icon_name [in] the name of an icon 


Returns: 


An newly allocated array describing the sizes at which the icon is available. The array should be freed 
with g_free() when it is no longer needed. 


6.9.3.17 void gtk_icon_theme_get_search_path (GtkIconTheme x icon_theme, gchar xx path] ], 
gint « n_elements) 


Gets the current search path. 


See gtk_icon_theme_set_search_path(). 


Parameters: 
icon_theme [in] a GtkIconTheme 


path [out] location to store a list of icon theme path directories or NULL The stored value should be 
freed with g_strfreev(). 


n_elements [out] location to store number of elements in path, or NULL 


Returns: 


void 
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6.9.3.18 gboolean gtk_icon_theme_has_icon (GtkIconTheme  icon_theme, const gchar x 
icon_name) 


Checks whether an icon theme includes an icon for a particular name. 


Parameters: 
icon_theme [in] a GtkIconTheme 


icon_name [in] the name of an icon 


Returns: 


TRUE if icon_theme includes an icon for icon_name. 


6.9.3.19 GList« gtk_icon_theme_list_icons (GtkIconTheme + icon_theme, const gchar * context) 


Lists the icons in the current icon theme. 
Only a subset of the icons can be listed by providing a context string. The set of values for the context 
string is system dependent, but will typically include such values as "Applications" and "MimeTypes". 
Parameters: 

icon_theme [in] a GtkIconTheme 


context [in] a string identifying a particular type of icon, or NULL to list all icons. 


Returns: 


a GList list holding the names of all the icons in the theme. You must first free each element in the list 
with g_free(), then free the list itself with g_list_free(). 


6.9.3.20  GdkPixbufx* gtk_icon_theme_load_icon (GtkIconTheme « icon_theme, const gchar + 
icon_name, gint size, GtkIconLookupFlags flags, GError xx error) 


Looks up an icon in an icon theme, scales it to the given size and renders it into a pixbuf. 


This is a convenience function; if more details about the icon are needed, use gtk_icon_theme_lookup_- 
icon() followed by gtk_icon_info_load_icon(). Note that you probably want to listen for icon theme 
changes and update the icon. This is usually done by connecting to the GtkWidget[in]:style-set signal. 
If for some reason you do not want to update the icon when the icon theme changes, you should consider 
using gdk_pixbuf_copy() to make a private copy of the pixbuf returned by this function. Otherwise GTK+ 
may need to keep the old icon theme loaded, which would be a waste of memory. 


Parameters: 
icon_theme [in] a GtkIconTheme 
icon_name [in] the name of the icon to lookup 


size [in] the desired icon size. The resulting icon may not be exactly this size; see gtk_icon_info_- 
load_icon(). 


flags [in] flags modifying the behavior of the icon lookup 


error [out] Location to store error information on failure, or NULL. 
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Returns: 


the rendered icon; this may be a newly created icon or a new reference to an internal icon, so you must 
not modify the icon. Use g_object_unref() to release your reference to the icon. NULL if the icon isn’t 
found. 


6.9.3.21 GtklIconInfox gtk_icon_theme_lookup_icon (GtkIconTheme + icon_theme, const gchar * 
icon_name, gint size, GtkIconLookupFlags flags) 


Looks up a named icon and returns a structure containing information such as the filename of the icon. 


The icon can then be rendered into a pixbuf using gtk_icon_info_load_icon(). (gtk_icon_theme_load_- 
icon() combines these two steps if all you need is the pixbuf.) 


Parameters: 


icon_theme [in] a GtkIconTheme 
icon_name [in] the name of the icon to lookup 
size [in] desired icon size 


flags [in] flags modifying the behavior of the icon lookup 


Returns: 


a GtkIconInfo structure containing information about the icon, or NULL if the icon wasn’t found. Free 
with gtk_icon_info_free() 


6.9.3.22  GtkIconThemex gtk_icon_theme_new (void) 


Creates a new icon theme object. 


Icon theme objects are used to lookup up an icon by name in a particular icon theme. Usually, you’ll want 
to use gtk_icon_theme_get_default() or gtk_icon_theme_get_for_screen() rather than creating a new icon 
theme object for scratch. 


Returns: 


the newly created GtkIconTheme object. 
6.9.3.23 void gtk_icon_theme_prepend_search_path (GtkIconTheme x icon_theme, const gchar x 
path) 


Prepends a directory to the search path. 


See gtk_icon_theme_set_search_path(). 


Parameters: 


icon_theme [in] a GtkIconTheme 


path [in] directory name to prepend to the icon path 


Returns: 


void 
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6.9.3.24 gboolean gtk_icon_theme_rescan if needed (GtkIconTheme x icon_theme) 


Checks to see if the icon theme has changed; if it has, any currently cached information is discarded and 
will be reloaded next time icon_theme is accessed. 


Parameters: 


icon_theme [in] a GtkIconTheme 


Returns: 


TRUE if the icon theme has changed and needed to be reloaded 


6.9.3.25 void gtk_icon_theme_set_custom_theme (GtkIconTheme x icon_theme, const gchar x 
theme_name) 


Sets the screen for an icon theme; theSets the name of the icon theme that the GtkIconTheme object uses 
overriding system configuration. 


This function cannot be called on the icon theme objects returned from gtk_icon_theme_get_default() and 
gtk_icon_theme_get_for_screen(). 


Parameters: 


icon_theme [in] a GtkIconTheme 


theme_name [in] name of icon theme to use instead of configured theme, or NULL to unset a previ- 
ously set custom theme 


Returns: 


void 


6.9.3.26 void gtk_icon_theme_set_screen (GtkIconTheme x icon_theme, GdkScreen x screen) 


Sets the screen for an icon theme; the screen is used to track the user’s currently configured icon theme, 
which might be different for different screens. 
Parameters: 


icon_theme [in] a GtkIconTheme 


screen [in] a GdkScreen 


Returns: 


void 


6.9.3.27 void gtk_icon_theme_set_search_path (GtkIconTheme x icon_theme, const gchar * 
path{ ], gint n_elements) 


Sets the search path for the icon theme object. 


When looking for an icon theme, GTK+ will search for a subdirectory of one or more of the directories in 
path with the same name as the icon theme. (Themes from multiple of the path elements are combined to 
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allow themes to be extended by adding icons in the user's home directory.) In addition if an icon found 
isn’t found either in the current icon theme or the default icon theme, and an image file with the right name 
is found directly in one of the elements of path, then that image will be used for the icon name. (This 
is legacy feature, and new icons should be put into the default icon theme, which is called DEFAULT_- 
THEME_NAME, rather than directly on the icon path.) 


Parameters: 


icon_theme [in] a GtkIconTheme 
path [in] array of directories that are searched for icon themes 


n_elements [in] number of elements in path. 


Returns: 


void 
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6.10 GtkModule 


6.10.1 Detailed Description 


This file defines the functions of GtkModule. 


Functions 


e G_BEGIN_DECLS gchar » _gtk_find_module (const gchar «name, const gchar *type) 


Looks for a dynamically module named name of type type in the standard GTK+ module search path. 


e gchar ** _gtk_get_module_path (const gchar «type) 


Determines the search path for a particular type of module. 


e void _gtk_modules_init (gint «argc, gchar x**xargv, const gchar *gtk_modules_args) 


initialises the modules 


e void _gtk_modules_settings_changed (GtkSettings *settings, const gchar *modules) 


Changes module settings. 


6.10.2 Function Documentation 
6.10.2.1 G_BEGIN_DECLS gchar» _gtk_find_module (const gchar x name, const gchar + type) 


Looks for a dynamically module named name of type type in the standard GTK+ module search path. 


Parameters: 
< name : the name of the module 


— type : the type of the module, for instance modules’, ’engines’, immodules’ 


Returns: 


the pathname to the found module, or NULL if it wasn’t found. free with g_free(). 


6.10.2.2 gchar*x _gtk_get_module_path (const gchar x type) 


Determines the search path for a particular type of module. 


Parameters: 


< type : the type of the module, for instance modules’, ’engines’, immodules’ 


Returns: 


the search path for the module type. Free with g_strfreev(. 
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6.10.2.3 void _gtk_modules_init (gint x argc, gchar xx*x argv, const gchar * gtk_modules_args) 
initialises the modules 


Parameters: 


— argc : argument count 
— argv : aggument list 


— gtk_modules_args : module args 


Returns: 


void 


6.10.2.4 void _gtk modules settings_changed (GtkSettings x settings, const gchar « modules) 
Changes module settings. 


Parameters: 


— settings : a GtkSettings 


— modules : modules path 


Returns: 


void 
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6.11 GtkClipboard 


6.11.1 Detailed Description 


The GtkClipboard object represents a clipboard of data shared between different processes or between 
different widgets in the same process. 


Each clipboard is identified by a name encoded as a GdkAtom. (Conversion to and from strings can be done 
with gdk_atom_intern() and gdk_atom_name().) The default clipboard corresponds to the "CLIPBOARD" 
atom; another commonly used clipboard is the "PRIMARY" clipboard, which, in X, traditionally contains 
the currently selected text. 


To support having a number of different formats on the clipboard at the same time, the clipboard mechanism 
allows providing callbacks instead of the actual data. When you set the contents of the clipboard, you can 
either supply the data directly (via functions like gtk_clipboard_set_text()), or you can supply a callback to 
be called at a later time when the data is needed (via gtk_clipboard_set_with_data() or gtk_clipboard_set_- 
with_owner().) Providing a callback also avoids having to make copies of the data when it is not needed. 


gtk_clipboard_set_with_data() and gtk_clipboard_set_with_owner() are quite similar; the choice between 
the two depends mostly on which is more convenient in a particular situation. The former is most useful 
when you want to have a blob of data with callbacks to convert it into the various data types that you adver- 
tise. When the clear_func you provided is called, you simply free the data blob. The latter is more useful 
when the contents of clipboard reflect the internal state of a GObject (As an example, for the PRIMARY 
clipboard, when an entry widget provides the clipboard’s contents the contents are simply the text within 
the selected region.) If the contents change, the entry widget can call gtk_clipboard_set_with_owner() to 
update the timestamp for clipboard ownership, without having to worry about clear_func being called. 


Requesting the data from the clipboard is essentially asynchronous. If the contents of the clipboard are 
provided within the same process, then a direct function call will be made to retrieve the data, but if they 
are provided by another process, then the data needs to be retrieved from the other process, which may take 
some time. To avoid blocking the user interface, the call to request the selection, gtk_clipboard_request_- 
contents() takes a callback that will be called when the contents are received (or when the request fails.) 
If you don’t want to deal with providing a separate callback, you can also use gtk_clipboard_wait_for_- 
contents(). What this does is run the GLib main loop recursively waiting for the contents. This can simplify 
the code flow, but you still have to be aware that other callbacks in your program can be called while this 
recursive mainloop is running. 


Along with the functions to get the clipboard contents as an arbitrary data chunk, there are also functions 
to retrieve it as text, gtk_clipboard_request_text() and gtk_clipboard_wait_for_text(). These functions take 
care of determining which formats are advertised by the clipboard provider, asking for the clipboard in 
the best available format and converting the results into the UTF-8 encoding. (The standard form for 
representing strings in GTK+.) 


Typedefs 


e typedef void(* GtkClipboardReceivedFunc )(GtkClipboard clipboard, GtkSelectionData 
*selection_data, gpointer data) 


A function to be called when the results of gtk_clipboard_request_contents() are received, or when the 
request fails. 


e typedef void(« GtkClipboardTextReceivedFunc )(GtkClipboard «clipboard, const gchar text, 
gpointer data) 


A function to be called when the results of gtk_clipboard_request_text() are received, or when the request 
fails. 
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typedef void(* GtkClipboardRichTextReceivedFunc )(GtkClipboard «clipboard, GdkAtom format, 
const guint8 «text, gsize length, gpointer data) 


A function to be called when the results of gtk_clipboard_request_rich_text() are received, or when the 
request fails. 


typedef void(* GtkClipboardImageReceivedFunc )(GtkClipboard «clipboard, GdkPixbuf *pixbuf, 
gpointer data) 


A function to be called when the results of gtk_clipboard_request_image() are received, or when the request 
fails. 


typedef void(* GtkClipboardTargetsReceivedFunc )(GtkClipboard «clipboard, GdkAtom xatoms, 
gint n_atoms, gpointer data) 


A function to be called when the results of gtk_clipboard_request_targets() are received, or when the request 
fails. 


typedef void(x* GtkClipboardGetFunc )(GtkClipboard «clipboard, GtkSelectionData *selection_- 
data, guint info, gpointer user_data_or_owner) 


A function that will be called to provide the contents of the selection. 


typedef void(* GtkClipboardClearFunc )(GtkClipboard «clipboard, gpointer user_data_or_owner) 


A function that will be called when the contents of the clipboard are changed or cleared. 


Functions 


GtkClipboard x gtk_clipboard_get_for_display (GdkDisplay «display, GdkAtom selection) 


Returns the clipboard object for the given selection. 


GtkClipboard x gtk_clipboard_get (GdkAtom selection) 


Returns the clipboard object for the given selection. 


GdkDisplay x gtk_clipboard_get_display (GtkClipboard *clipboard) 
Gets the GdkDisplay associated with clipboard. 


gboolean gtk_clipboard_set_with_data (GtkClipboard clipboard, const GtkTargetEntry targets, 
guint n_ targets, GtkClipboardGetFunc get_func, GtkClipboardClearFunc clear_func, gpointer 
user_data) 


Virtually sets the contents of the specified clipboard by providing a list of supported formats for the clipboard 
data and a function to call to get the actual data when it is requested. 


gboolean gtk_clipboard_set_with_owner (GtkClipboard clipboard, const GtkTargetEntry x*targets, 
guint n_ targets, GtkClipboardGetFunc get_func, GtkClipboardClearFunc clear_func, GObject 
xowner) 


Virtually sets the contents of the specified clipboard by providing a list of supported formats for the clipboard 
data and a function to call to get the actual data when it is requested. 


GObject x* gtk_clipboard_get_owner (GtkClipboard clipboard) 


If the clipboard contents callbacks were set with gtk_clipboard_set_with_owner(), and the gtk_clipboard_- 
set_with_data() or gtk_clipboard_clear() has not subsequently called, returns the owner set by gtk_- 
clipboard_set_with_owner(). 
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void gtk_clipboard_clear (GtkClipboard x*clipboard) 


Clears the contents of the clipboard. 


void gtk_clipboard_set_text (GtkClipboard «clipboard, const gchar *text, gint len) 


Sets the contents of the clipboard to the given UTF-8 string. 


void gtk_clipboard_set_image (GtkClipboard *clipboard, GdkPixbuf «pixbuf) 


Sets the contents of the clipboard to the given GdkPixbuf. 


void gtk_clipboard_request_contents (GtkClipboard «clipboard, GdkAtom target, GtkClipboard- 
ReceivedFunc callback, gpointer user_data) 


Requests the contents of clipboard as the given target. 


void gtk_clipboard_request_text (GtkClipboard «clipboard, GtkClipboardTextReceivedFunc call- 
back, gpointer user_data) 


Requests the contents of the clipboard as text. 


void gtk_clipboard_request_rich_text (GtkClipboard *clipboard, GtkTextBuffer «buffer, GtkClip- 
boardRichTextReceivedFunc callback, gpointer user_data) 


Requests the contents of the clipboard as rich text. 


void gtk clipboard_request_image (GtkClipboard «clipboard, GtkClipboardImageReceivedFunc 
callback, gpointer user_data) 


Requests the contents of the clipboard as image. 


void gtk_clipboard_request_targets (GtkClipboard «clipboard, GtkClipboardTargetsReceivedFunc 
callback, gpointer user_data) 


Requests the contents of the clipboard as list of supported targets. 


GtkSelectionData * gtk_clipboard_wait_for_contents (GtkClipboard «clipboard, GdkAtom target) 


Requests the contents of the clipboard using the given target. 


gchar * gtk _clipboard_wait_for_text (GtkClipboard *clipboard) 


Requests the contents of the clipboard as text and converts the result to UTF-8 if necessary. 


guint8 x gtk_clipboard_wait_for_rich_text (GtkClipboard «clipboard, GtkTextBuffer «buffer, Gd- 
kAtom xformat, gsize xlength) 


Requests the contents of the clipboard as rich text. 


GdkPixbuf x gtk_clipboard_wait_for_image (GtkClipboard *clipboard) 


Requests the contents of the clipboard as image and converts the result to a GdkPixbuf. 


gboolean gtk_clipboard_wait_for_targets (GtkClipboard *clipboard, GdkAtom targets, gint *n_- 
targets) 


Returns a list of targets that are present on the clipboard, or NULL if there aren't any targets available. 


gboolean gtk_clipboard_wait_is_text_available (GtkClipboard *clipboard) 


Test to see if there is text available to be pasted This is done by requesting the TARGETS atom and checking 
if it contains any of the supported text targets. 
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e gboolean gtk_clipboard_wait_is_rich_text_available (GtkClipboard clipboard, GtkTextBuffer 
*buffer) 


Test to see if there is rich text available to be pasted This is done by requesting the TARGETS atom and 
checking if it contains any of the supported rich text targets. 


e gboolean gtk_clipboard_wait_is_image available (GtkClipboard *clipboard) 


Test to see if there is an image available to be pasted This is done by requesting the TARGETS atom and 
checking if it contains any of the supported image targets. 


e gboolean gtk_clipboard_wait_is_target_available (GtkClipboard «clipboard, GdkAtom target) 
Checks if a clipboard supports pasting data of a given type. 


e void gtk_clipboard_set_can_store (GtkClipboard «clipboard, const GtkTargetEntry «targets, gint n_- 
targets) 


Hints that the clipboard data should be stored somewhere when the application exits or when gtk_- 
clipboard_store() is called. 


e void gtk_clipboard_store (GtkClipboard *clipboard) 


Stores the current clipboard data somewhere so that it will stay around after the application has quit. 


6.11.2 Typedef Documentation 


6.11.2.1 typedef void(* GtkClipboardClearFunc)(GtkClipboard «clipboard, gpointer 
user_data_or_owner) 
A function that will be called when the contents of the clipboard are changed or cleared. 


Once this has called, the user_data_or_owner argument will not be used again. 


Parameters: 


clipboard [in] the GtkClipboard 


user_data_or_owner [in] the user_data argument passed to gtk clipboard_set_with_data(), or the 
owner argument passed to gtk_clipboard_set_with_owner() 
Returns: 


void 


6.11.2.2 typedef void(* GtkClipboardGetFunc)(GtkClipboard «clipboard, GtkSelectionData 
*selection_data, guint info, gpointer user_data_or_owner) 


A function that will be called to provide the contents of the selection. 


If multiple types of data were advertised, the requested type can be determined from the info parameter 
or by checking the target field of selection_data. If the data could successfully be converted into then it 
should be stored into the selection_data object by calling gtk_selection_data_set() (or related functions 
such as gtk_selection_data_set_text()). If no data is set, the requestor will be informed that the attempt to 
get the data failed. 


Parameters: 


clipboard [in] the GtkClipboard 
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selection_data [in] a GtkSelectionData argument in which the requested data should be stored. 


info [in] the info field corresponding to the requested target from the GtkTargetEntry array passed to 
gtk_clipboard_set_with_data() or gtk_clipboard_set_with_owner(). 


user_data_or_owner [in] the user_data argument passed to gtk clipboard_set_with_data(), or the 
owner argument passed to gtk_clipboard_set_with_owner() 


Returns: 


void 


6.11.2.3 typedef void(* GtkClipboardImageReceivedFunc)(GtkClipboard «clipboard, GdkPixbuf 
«pixbuf, gpointer data) 


A function to be called when the results of gtk_clipboard_request_image() are received, or when the request 
fails. 
Parameters: 

clipboard [in] the GtkClipboard 

pixbuf [in] the received image 


data [in] the user_data supplied to gtk_clipboard_request_image(). 


Returns: 


void 


6.11.2.4 typedef void(« GtkClipboardReceivedFunc)(GtkClipboard «clipboard, GtkSelectionData 
*selection_data, gpointer data) 


A function to be called when the results of gtk_clipboard_request_contents() are received, or when the 
request fails. 


Parameters: 


clipboard [in] the GtkClipboard 


selection_data [in] a GtkSelectionData containing the data was received. If retrieving the data failed, 
then then length field of selection_data will be negative. 


data [in] the user_data supplied to gtk_clipboard_request_contents(). 


Returns: 


void 


6.11.2.5 typedef void(* GtkClipboardRichTextReceivedFunc)(GtkClipboard «clipboard, 
GdkAtom format, const guint8 «text, gsize length, gpointer data) 


A function to be called when the results of gtk_clipboard_request_rich_text() are received, or when the 
request fails. 
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Parameters: 


clipboard [in] the GtkClipboard 

format [in] a GdkAtom which identifies the clipboard to use. 

text [in] the received text 

length [in] the received text lenght 

data [in] the user_data supplied to gtk_clipboard_request_rich_text 


Returns: 


void 


6.11.2.6 typedef void(« GtkClipboardTargetsReceivedFunc)(GtkClipboard «clipboard, GdkAtom 
xatoms, gint n_atoms, gpointer data) 


A function to be called when the results of gtk_clipboard_request_targets() are received, or when the re- 
quest fails. 
Parameters: 


clipboard [in] the GtkClipboard 
atoms [in] the supported targets, as array of GdkAtom, or NULL if retrieving the data failed. 
n_atoms [in] the length of the atoms array. 


data [in] the user_data supplied to gtk_clipboard_request_targets(). 


Returns: 


void 


6.11.2.7 typedef void(« GtkClipboardTextReceivedFunc)(GtkClipboard «clipboard, const gchar 
«text, gpointer data) 


A function to be called when the results of gtk_clipboard_request_text() are received, or when the request 
fails. 


Parameters: 


clipboard [in] the GtkClipboard 
text [in] the text received, as a UTF-8 encoded string, or NULL if retrieving the data failed. 
data [in] the user_data supplied to gtk_clipboard_request_text(). 


Returns: 
void 
6.11.3 Function Documentation 
6.11.3.1 void gtk_clipboard_clear (GtkClipboard x clipboard) 


Clears the contents of the clipboard. 
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Generally this should only be called between the time you call gtk_clipboard_set_with_owner() or gtk_- 
clipboard_set_with_data(), and when the clear_func you supplied is called. Otherwise, the clipboard may 
be owned by someone else. 


Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


void 


6.11.3.2 GtkClipboardx gtk_clipboard_get (GdkAtom selection) 


Returns the clipboard object for the given selection. 


See gtk_clipboard_get_for_display() for complete details 


Parameters: 


selection [in] a GdkAtom which identifies the clipboard to use. 


Returns: 


the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a 
clipboard object has been created, it is persistent and, since it is owned by GTK+, must not be freed or 
unrefd. 


6.11.3.3 GdkDisplayx gtk_clipboard_get_display (GtkClipboard + clipboard) 
Gets the GdkDisplay associated with clipboard. 


Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


the GdkDisplay associated with clipboard 


6.11.3.4 GtkClipboardx gtk_clipboard_get_for_display (GdkDisplay * display, GdkAtom 
selection) 


Returns the clipboard object for the given selection. 


Cut/copy/paste menu items and keyboard shortcuts should use the default clipboard, returned by passing 
GDK_SELECTION_CLIPBOARD for selection. (GDK_NONE is supported as a synonym for GDK_- 
SELECTION_CLIPBOARD for backwards compatibility reasons.) The currently-selected object or text 
should be provided on the clipboard identified by GDK_SELECTION_PRIMARY. Cut/copy/paste menu 
items conceptually copy the contents of the GDK_SELECTION_PRIMARY clipboard to the default clip- 
board, i.e. they copy the selection to what the user sees as the clipboard. 


(Passing GDK_NONE is the same as using gdk_atom_intern ("CLIPBOARD", FALSE). See 
http://www. freedesktop.org/Standards/clipboards-spec for a detailed discussion of 
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the "CLIPBOARD" vs. "PRIMARY" selections under the X window system. On Win32 the GDK_- 
SELECTION_PRIMARY clipboard is essentially ignored.) 


It’s possible to have arbitrary named clipboards; if you do invent new clipboards, you should prefix the 
selection name with an underscore (because the ICCCM requires that nonstandard atoms are underscore- 
prefixed), and namespace it as well. For example, if your application called "Foo" has a special-purpose 
clipboard, you might call it "_FOO_SPECIAL_ CLIPBOARD". 
Parameters: 

display [in] the display for which the clipboard is to be retrieved or created 


selection [in] a GdkAtom which identifies the clipboard to use. 


Returns: 


the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a 
clipboard object has been created, it is persistent and, since it is owned by GTK+, must not be freed or 
unrefd. 


6.11.3.5 GObjectx gtk_clipboard_get_owner (GtkClipboard x clipboard) 


If the clipboard contents callbacks were set with gtk_clipboard_set_with_owner(), and the gtk_clipboard_- 
set_with_data() or gtk_clipboard_clear() has not subsequently called, returns the owner set by gtk _- 
clipboard_set_with_owner‘(). 


Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


the owner of the clipboard, if any; otherwise NULL. 


6.11.3.6 void gtk_clipboard_request_contents (GtkClipboard « clipboard, GdkAtom target, 
GtkClipboardReceivedFunc callback, gpointer user_data) 
Requests the contents of clipboard as the given target. 


When the results of the result are later received the supplied callback will be called. 


Parameters: 
clipboard [in] a GtkClipboard 
targets [in] an atom representing the form into which the clipboard owner should convert the selection. 


callback [in] A function to call when the results are received (or the retrieval fails). If the retrieval 
fails the length field of selection_data will be negative. 


user_data [in] user data to pass to callback 


Returns: 


void 
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6.11.3.7 void gtk_clipboard_request_image (GtkClipboard ~ clipboard, 
GtkClipboardImageReceivedF unc callback, gpointer user_data) 

Requests the contents of the clipboard as image. 

When the image is later received, it will be converted to a GdkPixbuf, and callback will be called. 


The pixbuf parameter to callback will contain the resulting GdkPixbuf if the request succeeded, or NULL 
if it failed. This could happen for various reasons, in particular if the clipboard was empty or if the contents 
of the clipboard could not be converted into an image. 


Parameters: 


clipboard [in] a GtkClipboard 


callback [in] a function to call when the image is received, or the retrieval fails. (It will always be 
called one way or the other.) 


user_data [in] user data to pass to callback. 


Returns: 


void 


6.11.3.8 void gtk_clipboard_request_rich_text (GtkClipboard x clipboard, GtkTextBuffer x buffer, 
GtkClipboardRichTextReceivedFunc callback, gpointer user_data) 

Requests the contents of the clipboard as rich text. 

When the rich text is later received, callback will be called. 


The text parameter to callback will contain the resulting rich text if the request succeeded, or NULL if 
it failed. The length parameter will contain text’s length. This function can fail for various reasons, in 
particular if the clipboard was empty or if the contents of the clipboard could not be converted into rich 
text form. 
Parameters: 

clipboard [in] a GtkClipboard 

buffer [in] a GtkTextBuffer 


callback [in] a function to call when the text is received, or the retrieval fails. (It will always be called 
one way or the other.) 


user_data [in] user data to pass to callback. 


Returns: 


void 


6.11.3.9 void gtk_clipboard_request_targets (GtkClipboard x clipboard, 
GtkClipboardTargetsReceivedFunc callback, gpointer user_data) 

Requests the contents of the clipboard as list of supported targets. 

When the list is later received, callback will be called. 


The targets parameter to callback will contain the resulting targets if the request succeeded, or NULL if it 
failed. 
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Parameters: 


clipboard [in] a GtkClipboard 


callback [in] a function to call when the targets are received, or the retrieval fails. (It will always be 
called one way or the other.) 


user_data [in] user data to pass to callback. 


Returns: 


void 


6.11.3.10 void gtk_clipboard_request_text (GtkClipboard x clipboard, 
GtkClipboardTextReceivedFunc callback, gpointer user_data) 

Requests the contents of the clipboard as text. 

When the text is later received, it will be converted to UTF-8 if necessary, and callback will be called. 


The text parameter to callback will contain the resulting text if the request succeeded, or NULL if it failed. 
This could happen for various reasons, in particular if the clipboard was empty or if the contents of the 
clipboard could not be converted into text form. 


Parameters: 


clipboard [in] a GtkClipboard 


callback [in] a function to call when the text is received, or the retrieval fails. (It will always be called 
one way or the other.) 


user_data [in] user data to pass to callback. 


Returns: 


void 


6.11.3.11 void gtk_clipboard_set_can_store (GtkClipboard ~ clipboard, const GtkTargetEntry + 
targets, gint n_targets) 


Hints that the clipboard data should be stored somewhere when the application exits or when gtk_- 
clipboard_store() is called. 

This value is reset when the clipboard owner changes. Where the clipboard data is stored is platform 
dependent, see gdk_display_store_clipboard() for more information. 

Parameters: 


clipboard [in] a GtkClipboard 


targets [in] array containing information about which forms should be stored or NULL to indicate 
that all forms should be stored. 


n_targets [in] number of elements in targets 


Returns: 


void 
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6.11.3.12 void gtk_clipboard_set_image (GtkClipboard « clipboard, GdkPixbuf x pixbuf) 


Sets the contents of the clipboard to the given GdkPixbuf. 

GTK+ will take responsibility for responding for requests for the image, and for converting the image into 
the requested format. 

Parameters: 


clipboard [in] a GtkClipboard 
pixbuf [in] a GdkPixbuf 


Returns: 


void 


6.11.3.13 void gtk_clipboard_set_text (GtkClipboard « clipboard, const gchar * text, gint len) 


Sets the contents of the clipboard to the given UTF-8 string. 


GTK+ will make a copy of the text and take responsibility for responding for requests for the text, and for 
converting the text into the requested format. 


Parameters: 


clipboard [in] a GtkClipboard object 
text [in] a UTF-8 string. 


len [in] length of text, in bytes, or -1, in which case the length will be determined with strlen(). 


Returns: 


void 


6.11.3.14 gboolean gtk_clipboard_set_with_data (GtkClipboard « clipboard, const 
GtkTargetEntry * targets, guint n_targets, GtkClipboardGetFunc get_func, 
GtkClipboardClearFunc clear_func, gpointer user_data) 


Virtually sets the contents of the specified clipboard by providing a list of supported formats for the clip- 
board data and a function to call to get the actual data when it is requested. 


Parameters: 


clipboard [in] a GtkClipboard 

targets [in] array containing information about the available forms for the clipboard data 
n_targets [in] number of elements in targets 

get_func [in] function to call to get the actual clipboard data 


clear_func [in] when the clipboard contents are set again, this function will be called, and get_func 
will not be subsequently called. 


user_data [in] user data to pass to get_func and clear_func. 


Returns: 


TRUE if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback 
functions will be ignored. 
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6.11.3.15 gboolean gtk_clipboard_set_with_owner (GtkClipboard x clipboard, const 
GtkTargetEntry x targets, guint n_targets, GtkClipboardGetFunc get_func, 
GtkClipboardClearFunc clear_func, GObject x owner) 


Virtually sets the contents of the specified clipboard by providing a list of supported formats for the clip- 
board data and a function to call to get the actual data when it is requested. 


The difference between this function and gtk_clipboard_set_with_data() is that instead of an generic user_- 
data pointer, a GObject is passed in. 


Parameters: 


clipboard [in] a GtkClipboard 

targets [in] array containing information about the available forms for the clipboard data 
n_targets [in] number of elements in targets 

get_func [in] function to call to get the actual clipboard data 


clear_func [in] when the clipboard contents are set again, this function will be called, and get_func 
will not be subsequently called. 


user_data [in] an object that "owns" the data. This object will be passed to the callbacks when called. 
Returns: 


TRUE if setting the clipboard data succeeded. If setting the clipboard data failed the provided callback 
functions will be ignored. 


6.11.3.16 void gtk_clipboard_store (GtkClipboard = clipboard) 
Stores the current clipboard data somewhere so that it will stay around after the application has quit. 


Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


void 


6.11.3.17 GtkSelectionDatax gtk_clipboard_wait_for_contents (GtkClipboard x clipboard, 
GdkAtom target) 
Requests the contents of the clipboard using the given target. 


This function waits for the data to be received using the main loop, so events, timeouts, etc, may be 
dispatched during the wait. 


Parameters: 

clipboard [in] a GtkClipboard 

targets [in] an atom representing the form into which the clipboard owner should convert the selection. 
Returns: 


a newly-allocated GtkSelectionData object or NULL if retrieving the given target failed. If non-NULL, 
this value must be freed with gtk_selection_data_free() when you are finished with it. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


116 Module Documentation 


6.11.3.18 GdkPixbufx gtk_clipboard_wait_for_image (GtkClipboard « clipboard) 


Requests the contents of the clipboard as image and converts the result to a GdkPixbuf. 


This function waits for the data to be received using the main loop, so events, timeouts, etc, may be 
dispatched during the wait. 


Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


a newly-allocated GdkPixbuf object which must be disposed with g_object_unref(), or NULL if re- 
trieving the selection data failed. (This could happen for various reasons, in particular if the clipboard 
was empty or if the contents of the clipboard could not be converted into an image.) 


6.11.3.19 guint8* gtk_clipboard_wait_for_rich_text (GtkClipboard x clipboard, GtkTextBuffer x 
buffer, GdkAtom x format, gsize x length) 

Requests the contents of the clipboard as rich text. 

This function waits for the data to be received using the main loop, so events, timeouts, etc, may be 

dispatched during the wait. 

Parameters: 


clipboard [in] a GtkClipboard 
buffer [in] a GtkTextBuffer 
format [out] return location for the format of the returned data 


length [out] return location for the length of the returned data 


Returns: 


a newly-allocated binary block of data which must be freed with g_free(), or NULL if retrieving the 
selection data failed. (This could happen for various reasons, in particular if the clipboard was empty 
or if the contents of the clipboard could not be converted into text form.) 


6.11.3.20 gboolean gtk_clipboard_wait_for_targets (GtkClipboard + clipboard, GdkAtom ** 
targets, gint x n_targets) 
Returns a list of targets that are present on the clipboard, or NULL if there aren't any targets available. 


The returned list must be freed with g_free(). This function waits for the data to be received using the main 
loop, so events, timeouts, etc, may be dispatched during the wait. 


Parameters: 
clipboard [in] a GtkClipboard 
targets [out] location to store an array of targets. The result stored here must be freed with g_free(). 
n_targets [out] location to store number of items in targets. 

Returns: 


TRUE if any targets are present on the clipboard, otherwise FALSE. 
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6.11.3.21 gchar» gtk_clipboard_wait_for_text (GtkClipboard x clipboard) 


Requests the contents of the clipboard as text and converts the result to UTF-8 if necessary. 

This function waits for the data to be received using the main loop, so events, timeouts, etc, may be 
dispatched during the wait. 

Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


a newly-allocated UTF-8 string which must be freed with g_free(), or NULL if retrieving the selection 
data failed. (This could happen for various reasons, in particular if the clipboard was empty or if the 
contents of the clipboard could not be converted into text form.) 


6.11.3.22 gboolean gtk_clipboard_wait_is_image_ available (GtkClipboard « clipboard) 
Test to see 1f there is an image available to be pasted This is done by requesting the TARGETS atom and 
checking if it contains any of the supported image targets. 


This function waits for the data to be received using the main loop, so events, timeouts, etc, may be 
dispatched during the wait. 


This function is a little faster than calling gtk_clipboard_wait_for_image() since it doesn’t need to retrieve 
the actual image data. 


Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


TRUE is there is an image available, FALSE otherwise. 


6.11.3.23 gboolean gtk_clipboard_wait_is_rich_text_available (GtkClipboard = clipboard, 
GtkTextBuffer x buffer) 


Test to see if there is rich text available to be pasted This is done by requesting the TARGETS atom and 
checking if it contains any of the supported rich text targets. 


This function waits for the data to be received using the main loop, so events, timeouts, etc, may be 
dispatched during the wait. 


This function is a little faster than calling gtk_clipboard_wait_for_rich_text() since it doesn’t need to re- 
trieve the actual text. 


Parameters: 


clipboard [in] a GtkClipboard 
buffer [in] a GtkTextBuffer 


Returns: 


TRUE is there is rich text available, FALSE otherwise. 
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6.11.3.24 gboolean gtk_clipboard_wait_is_target_available (GtkClipboard « clipboard, GdkAtom 
target) 

Checks if a clipboard supports pasting data of a given type. 

This function can be used to determine if a "Paste" menu item should be insensitive or not. 

If you want to see if there's text available on the clipboard, use gtk_clipboard_wait_is_text_available() 

instead. 

Parameters: 


clipboard [in] a GtkClipboard 
target [in] A GdkAtom indicating which target to look for. 


Returns: 


TRUE if the target is available, FALSE otherwise. 


6.11.3.25 gboolean gtk_clipboard_wait_is_text_available (GtkClipboard * clipboard) 
Test to see if there is text available to be pasted This is done by requesting the TARGETS atom and checking 
if it contains any of the supported text targets. 


This function waits for the data to be received using the main loop, so events, timeouts, etc, may be 
dispatched during the wait. 


This function is a little faster than calling gtk_clipboard_wait_for_text() since it doesn’t need to retrieve 
the actual text. 


Parameters: 


clipboard [in] a GtkClipboard 


Returns: 


TRUE is there is text available, FALSE otherwise. 
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6.12 Standard Gtk Widgets 


Modules 


Abstract Base Classes 
Windows 

Display Widgets 

Buttons and Toggles 
Numeric / Text Data Entry 
Multiline Text Editor 

Tree, List and Icon Grid Widgets 
Menus, Combo Box, Toolbar 
Layout Containers 

Scrolling 

Ornaments 

Miscellaneous Widgets 
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6.13 Abstract Base Classes 


Modules 


e GtkBin 


The GtkBin widget is a container with just one child. 


e GtkBox 


GtkBox is an abstract widget which encapsulates functionallity for a particular kind of container, one that 
organizes a variable number of widgets into a rectangular area. 


e GtkContainer 


A GTK+ user interface is constructed by nesting widgets inside widgets, Container widgets are the inner 
nodes in the resulting tree of widgets: they contain other widgets. 


e Gtkltem 
The GtkItem widget is an abstract base class for GtkMenultem, GtkListltem and GtkTreeltem. 


e GtkMisc 


The GtkMisc widget is an abstract widget which is not useful itself. but is used to derive subclasses which 
have alignment and padding attributes. 


¢ GtkScale 


A GtkScale is a slider control used to select a numeric value. 


e GtkScrollBar 
The GtkScrollbar widget is an abstract base class for GtkHScrollbar and GtkVScrollbar. 


e GtkRange 


Base class for widgets which visualize an adjustment. 


e GtkWidget 


GtkWidget is Base class for all GTK Widgets, GtkWidget introduces style properties - these are basically 
object properties that are stored not on the object, but in the style object associated to the widget. 
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6.14 GtkBin 


6.14.1 Detailed Description 


The GtkBin widget is a container with just one child. 


It is not very useful itself, but it is useful for deriving subclasses, since it provides common code needed 
for handling a single child widget. 


Many GTK+ widgets are subclasses of GtkBin, including GtkWindow, GtkButton, GtkFrame, GtkHandle- 
Box, and GtkScrolledWindow. 
Data Structures 


e struct _GtkBin 


GtkBin instance structure. 


e struct _GtkBinClass 


GtkBin instance class structure. 


Functions 


e GtkWidget * gtk_bin_get_child (GtkBin *bin) 
Gets the child of the GtkBin, or NULL if the bin contains no child widget. 


6.14.2 Function Documentation 
6.14.2.1 GtkWidgetx gtk_bin_get_child (GtkBin « bin) 


Gets the child of the GtkBin, or NULL if the bin contains no child widget. 


The returned widget does not have a reference added, so you do not need to unref it. 


Parameters: 


— bin : a GtkBin 


Returns: 


pointer to child of the GtkBin 
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6.15 GtkBox 


6.15.1 Detailed Description 


GtkBox is an abstract widget which encapsulates functionallity for a particular kind of container, one that 
organizes a variable number of widgets into a rectangular area. 


GtkBox currently has two derived classes, GtkHBox and GtkV Box. 


The rectangular area of a GtkBox is organized into either a single row or a single column of child widgets 
depending upon whether the box is of type GtkHBox or GtkVBox, respectively. Thus, all children of a 
GtkBox are allocated one dimension in common, which is the height of a row, or the width of a column. 


GtkBox uses a notion of packing. Packing refers to adding widgets with reference to a particular position 
in a GtkContainer. For a GtkBox, there are two reference positions: the start and the end of the box. For 
a GtkVBox, the start is defined as the top of the box and the end is defined as the bottom. For a GtkKHBox 
the start is defined as the left side and the end is defined as the right side. 


Use repeated calls to gtk_box_pack_start() to pack widgets into a GtkBox from start to end. Use gtk_box_- 
pack_end() to add widgets from end to start. You may intersperse these calls and add widgets from both 
ends of the same GtkBox. 


Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults() to pack widgets into a GtkBox if you 
do not need to specify the expand, fill, or padding attributes of the child to be added. 


Because GtkBox is a GtkContainer, you may also use gtk_container_add() to insert widgets into the box, 
and they will be packed as if with gtk_box_pack_start_defaults(). Use gtk_container_remove() to remove 
widgets from the GtkBox. 


Use gtk_box_set_homogeneous() to specify whether or not all children of the GtkBox are forced to get the 
same amount of space. 


Use gtk_box_set_spacing() to determine how much space will be minimally placed between all children in 
the GtkBox. 


Use gtk_box_reorder_child() to move a GtkBox child to a different place in the box. 


Use gtk_box_set_child_packing() to reset the expand, fill, and padding attributes of any GtkBox child. Use 
gtk_box_query_child_packing() to query these fields. 


Data Structures 


e struct _GtkBox 


GtkBox instance structure. 


e struct _GtkBoxClass 


GtkBox instance class structure. 


Functions 


e void gtk_box_pack_start (GtkBox *box, GtkWidget «child, gboolean expand, gboolean fill, guint 
padding) 
Adds child to box, packed with reference to the start of box. 


e void gtk _box_pack_end (GtkBox xbox, GtkWidget «child, gboolean expand, gboolean fill, guint 
padding) 
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Adds child to box, packed with reference to the end of box. 


e void gtk_box_pack_start_defaults (GtkBox xbox, GtkWidget *widget) 


Adds widget to box, packed with reference to the start of box. 


e void gtk_box_pack_end_defaults (GtkBox xbox, GtkWidget *widget) 


Adds widget to box, packed with reference to the end of box. 


e void gtk_box_set_homogeneous (GtkBox «box, gboolean homogeneous) 


Sets the homogeneous field of GtkBox, controlling whether or not all children of box are given equal space 
in the box. 


e gboolean gtk_box_get_homogeneous (GtkBox *box) 


Returns whether the box is homogeneous (all children are the same size). 


e void gtk_box_set_spacing (GtkBox *box, gint spacing) 


Sets the spacing field of GtkBox, which is the number of pixels to place between children of box. 


e gint gtk_box_get_spacing (GtkBox *box) 


Gets the value set by gtk_box_set_spacing(). 


e void gtk_box_reorder_child (GtkBox xbox, GtkWidget «child, gint position) 


Moves child to a new position in the list of box children.The list is the children field of GtkBox, and contains 
both widgets packed GTK_PACK_START as well as widgets packed GTK_PACK_END, in the order that 
these widgets were added to box. 


e void gtk_box_query_child_packing (GtkBox xbox, GtkWidget «child, gboolean «expand, gboolean 
*fill, guint x~padding, GtkPackType *pack_type) 


Returns information about how child is packed into box. 


e void gtk_box_set_child_packing (GtkBox «box, GtkWidget *child, gboolean expand, gboolean fill, 
guint padding, GtkPackType pack_type) 


Sets the way child is packed into box. 


6.15.2 Function Documentation 
6.15.2.1 gboolean gtk_box_get_homogeneous (GtkBox * box) 


Returns whether the box is homogeneous (all children are the same size). 


See gtk_box_set_homogeneous(). 


Parameters: 


< box : a GtkBin 


Returns: 


TRUE if the box is homogeneous. 
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6.15.2.2 gint gtk_box_get_spacing (GtkBox « box) 
Gets the value set by gtk_box_set_spacing(). 


Parameters: 


— box : a GtkBin 


Returns: 


spacing between children 


6.15.2.3 void gtk_box_pack_end (GtkBox * box, GtkWidget x child, gboolean expand, gboolean 
fill, guint padding) 


Adds child to box, packed with reference to the end of box. 


The child is packed after any other child packed with reference to the end of box. 


Parameters: 
< box : a GtkBox. 


— child : the GtkWidget to be added to box. 


— expand : TRUE if the new child is to be given extra space allocated to box. The extra space will 
be divided evenly between all children of box that use this option. 


— fill : TRUE if space given to child by the expand option is actually allocated to child, rather than just 
padding it. This parameter has no effect if expand is set to FALSE. A child is always allocated 
the full height of a GtkHBox and the full width of a GtkVBox. This option affects the other 
dimension. 


— padding : extra space in pixels to put between this child and its neighbors, over and above the 
global amount specified by spacing in GtkBox. If child is a widget at one of the reference ends 
of box, then padding pixels are also put between child and the reference edge of box. 

Returns: 


void 


6.15.2.4 void gtk_box_pack_end_defaults (GtkBox « box, GtkWidget « widget) 


Adds widget to box, packed with reference to the end of box. 

The child is packed after any other child packed with reference to the end of box. Parameters for how to 
pack the child widget, expand, fill, and padding in GtkBoxChild, are given their default values, TRUE, 
TRUE, and 0, respectively. 

Parameters: 


— box : a GtkBin 
— widget : a GtkBin 


Returns: 


void 
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6.15.2.5 void gtk_box_pack_start (GtkBox * box, GtkWidget x child, gboolean expand, gboolean 
fill, guint padding) 


Adds child to box, packed with reference to the start of box. 


The child is packed after any other child packed with reference to the start of box. 


Parameters: 


— box : a GtkBox. 
— child : the GtkWidget to be added to box. 


— expand : TRUE if the new child is to be given extra space allocated to box. The extra space will 
be divided evenly between all children of box that use this option. 


— fill : TRUE if space given to child by the expand option is actually allocated to child, rather than just 
padding it. This parameter has no effect if expand is set to FALSE. A child is always allocated 
the full height of a GtkHBox and the full width of a GtkVBox. This option affects the other 
dimension. 


— padding : extra space in pixels to put between this child and its neighbors, over and above the 
global amount specified by spacing in GtkBox. If child is a widget at one of the reference ends 
of box, then padding pixels are also put between child and the reference edge of box. 


Returns: 


void 


6.15.2.6 void gtk_box_pack_start_defaults (GtkBox « box, GtkWidget « widget) 


Adds widget to box, packed with reference to the start of box. 


The child is packed after any other child packed with reference to the start of box. Parameters for how 
to pack the child widget, expand, fill, and padding in GtkBoxChild, are given their default values, TRUE, 
TRUE, and 0, respectively. 


Parameters: 


— box : a GtkBin 
— widget : the GtkWidget to be added to box. 


Returns: 


void 


6.15.2.7 void gtk_box_query_child_packing (GtkBox « box, GtkWidget > child, gboolean * expand, 
gboolean x fill, guint * padding, GtkPackType x pack_type) 


Returns information about how child is packed into box. 


Parameters: 
— box : a GtkBin 
— child : the GtkWidget of the child to query. 
— expand : the returned value of the expand field in GtkBoxChild. 
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> fill : the returned value of the fill field in GtkBoxChild. 
> padding : the returned value of the padding field in GtkBoxChild. 
[outs] pack_type : the returned value of the pack field in GtkBoxChild. 


Returns: 


void 


6.15.2.8 void gtk_box_reorder_child (GtkBox x box, GtkWidget * child, gint position) 


Moves child to a new position in the list of box children.The list is the children field of GtkBox, and 
contains both widgets packed GTK_PACK_START as well as widgets packed GTK_PACK_END, in the 
order that these widgets were added to box. 


A widget’s position in the box children list determines where the widget is packed into box. A child widget 
at some position in the list will be packed just after all other widgets of the same packing type that appear 
earlier in the list. 
Parameters: 

— box : a GtkBin 

— child : the GtkWidget to move. 


— position : the new position for child in the children list of GtkBox, starting from 0. If negative, 
indicates the end of the list. 


Returns: 


void 


6.15.2.9 void gtk_box_set_child_packing (GtkBox + box, GtkWidget x child, gboolean expand, 
gboolean fill, guint padding, GtkPackType pack_type) 


Sets the way child is packed into box. 


Parameters: 
— box : a GtkBin 
— child : the GtkWidget of the child to set. 
— expand : the new value of the expand field in GtkBoxChild. 
— fill : the new value of the fill field in GtkBoxChild. 
— padding : the new value of the padding field in GtkBoxChild. 
— pack_type : the new value of the pack field in GtkBoxChild. 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.15 GtkBox 127 


6.15.2.10 void gtk_box_set_homogeneous (GtkBox « box, gboolean homogeneous) 


Sets the homogeneous field of GtkBox, controlling whether or not all children of box are given equal space 
in the box. 


Parameters: 


— box : a GtkBin 


— homogeneous : a boolean value, TRUE to create equal allotments, FALSE for variable allotments. 


Returns: 


void 


6.15.2.11 void gtk_box_set_spacing (GtkBox « box, gint spacing) 
Sets the spacing field of GtkBox, which is the number of pixels to place between children of box. 
Parameters: 


— fill : a GtkBin 


— spacing : the number of pixels to put between children. 


Returns: 


void 
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6.16 GtkContainer 


6.16.1 Detailed Description 


A GTK+ user interface is constructed by nesting widgets inside widgets, Container widgets are the inner 
nodes in the resulting tree of widgets: they contain other widgets. 


So, for example, you might have a GtkWindow containing a GtkFrame containing a GtkLabel. If you 
wanted an image instead of a textual label inside the frame, you might replace the GtkLabel widget with a 
GtkImage widget. 


There are two major kinds of container widgets in GTK+. Both are subclasses of the abstract GtkContainer 
base class. 


The first type of container widget has a single child widget and derives from GtkBin. These containers 
are decorators, which add some kind of functionality to the child. For example, a GtkButton makes its 
child into a clickable button; a GtkFrame draws a frame around its child and a Gtk Window places its child 
widget inside a top-level window. 


The second type of container can have more than one child; its purpose is to manage layout. This means 
that these containers assign sizes and positions to their children. For example, a GtkHBox arranges its 
children in a horizontal row, and a GtkTable arranges the widgets it contains in a two-dimensional grid. 


To fulfill its task, a layout container must negotiate the size requirements with its parent and its children. 
This negotiation is carried out in two phases, size requisition and size allocation. 


Size Requisition 
The size requisition of a widget is it’s desired width and height. This is represented by a GtkRequisition. 
How a widget determines its desired size depends on the widget. A GtkLabel, for example, requests enough 


space to display all its text. Container widgets generally base their size request on the requisitions of their 
children. 


The size requisition phase of the widget layout process operates top-down. It starts at a top-level widget, 
typically a GtkWindow. The top-level widget asks its child for its size requisition by calling gtk_widget_- 
size_request(). To determine its requisition, the child asks its own children for their requisitions and so on. 
Finally, the top-level widget will get a requisition back from its child. 


Size Allocation 


When the top-level widget has determined how much space its child would like to have, the second phase 
of the size negotiation, size allocation, begins. Depending on its configuration (see gtk_window_set_- 
resizable()), the top-level widget may be able to expand in order to satisfy the size request or it may have 
to ignore the size request and keep its fixed size. It then tells its child widget how much space it gets by 
calling gtk_widget_size_allocate(). The child widget divides the space among its children and tells each 
child how much space it got, and so on. Under normal circumstances, a Gtk Window will always give its 
child the amount of space the child requested. 


A child’s size allocation is represented by a GtkAllocation. This struct contains not only a width and height, 
but also a position (That is X and Y coordinates), so that containers can tell their children not only how 
much space they have gotten, but also where they are positioned inside the space available to the container. 


Widgets are required to honor the size allocation they receive; a size request is only a request, and widgets 
must be able to cope with any size. 


Child properties 
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GtkContainer introduces child properties - these are object properties that are not specific to either the 
container or the contained widget, but rather to their relation. Typical examples of child properties are the 
position or pack-type of a widget which is contained in a GtkBox. 


Use gtk_container_class_install_child_property() to install child properties for a container class and gtk_- 
container_class_find_child_property() or gtk_container_class_list_child_properties() to get information 
about existing child properties. 


To set the value of a child property, use gtk_container_child_set_property(), gtk_container_child_set() or 
gtk_container_child_set_valist(). To obtain the value of a child property, use gtk_container_child_get_- 
property(), gtk_container_child_get() or gtk_container_child_get_valist(). To emit notification about child 
property changes, use gtk_widget_child_notify(). 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkContainer 


GtkContainer instance structure. 


e struct _GtkContainerClass 


GtkContainer instance class structure. 


Functions 


e void gtk_container_set_border_width (GtkContainer «container, guint border_width) 


Sets the border width of the container. 


e guint gtk_container_get_border_width (GtkContainer *container) 


Retrieves the border width of the container. 


e void gtk_container_add (GtkContainer *container, GtkWidget *widget) 


Adds widget to container. 


e void gtk_container_remove (GtkContainer «container, GtkWidget «widget) 


Removes widget from container. 


e void gtk_container_set_resize_mode (GtkContainer *container, GtkResizeMode resize_mode) 


Sets the resize mode for the container. 


e GtkResizeMode gtk_container_get_resize_mode (GtkContainer container) 


Returns the resize mode for the container. 


e void gtk_container_check_resize (GtkContainer *container) 


Checks resize mode for the container. 


e void gtk_container_foreach (GtkContainer «container, GtkCallback callback, gpointer callback_- 
data) 
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Invokes callback on each non-internal child of container. 


GList * gtk_container_get_children (GtkContainer *container) 


Returns the container's non-internal children. 


void gtk_container_propagate_expose (GtkContainer *container, GtkWidget *child, GdkEventEx- 
pose *event) 


When a container receives an expose event, it must send synthetic expose events to all children that don't 
have their own GdkWindows. 


void gtk_container_set_focus_chain (GtkContainer *container, GList *focusable_widgets) 


Sets a focus chain, overriding the one computed automatically by GTK. 


gboolean gtk_container_get_focus_chain (GtkContainer «container, GList **focusable_widgets) 


Retrieves the focus chain of the container, if one has been set explicitly. 


void gtk_container_unset_focus_chain (GtkContainer *container) 


Removes a focus chain explicitly set with gtk_container_set_focus_chain(). 


void gtk_container_set_reallocate_redraws (GtkContainer «container, gboolean needs_redraws) 


Sets the reallocate_redraws flag of the container to the given value. 


void gtk_container_set_focus_child (GtkContainer «container, GtkWidget *child) 


Sets focus for the container current chaild. 


void gtk_container_set_focus_vadjustment (GtkContainer «container, GtkAdjustment 
*xadjustment) 


Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the 
adjustment is scrolled to show that widget. 


GtkAdjustment * gtk_container_get_focus_vadjustment (GtkContainer «container) 


Retrieves the vertical focus adjustment for the container. 


void gtk_container_set_focus_hadjustment (GtkContainer «container, GtkAdjustment 
*adjustment) 


Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the 
adjustment is scrolled to show that widget. 


GtkAdjustment * gtk_container_get_focus_hadjustment (GtkContainer *container) 


Retrieves the horizontal focus adjustment for the container. 


void gtk_container_resize_children (GtkContainer container) 


Jn gtk_container_resize_children 


GType gtk_container_child_type (GtkContainer *container) 
Returns the type of the children supported by the container. 


void gtk_container_class_install_child_property (GtkContainerClass x*cclass, guint property_id, 
GParamSpec *pspec) 


Installs a child property on a container class. 
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e GParamSpec x gtk container_class_find_child property (GObjectClass *cclass, const gchar 
*property_name) 


Finds a child property of a container class by name. 


e GParamSpec ** gtk container_class_list_child properties (GObjectClass x*cclass, guint *n_- 
properties) 


Returns all child properties of a container class. 


e void gtk_container_add_with_properties (GtkContainer «container, GtkWidget *widget, const gchar 
*first_prop_name,...) G_GNUC_NULL_TERMINATED 


Adds widget to container, setting child properties at the same time. 


e void gtk_container_child_set (GtkContainer *container, Gtk Widget «child, const gchar *first_prop_- 
name,...) GGNUC_NULL_TERMINATED 


Sets one or more child properties for child and container. 


e void gtk_container_child_ get (GtkContainer «container, GtkWidget «child, const gchar *first_prop_- 
name,...) GGNUC_NULL_TERMINATED 


Gets the values of one or more child properties for child and container. 


e void gtk_container_child_set_valist (GtkContainer *container, GtkWidget child, const gchar 
*first_property_name, va_list var_args) 


Sets one or more child properties for child and container. 


e void gtk container_child_get_valist (GtkContainer «container, GtkWidget *child, const gchar 
*first_property_name, va_list var_args) 


Gets the values of one or more child properties for child and container. 


e void gtk_container_child_set_property (GtkContainer «container, GtkWidget «child, const gchar 
*property_name, const GValue «value) 


Sets a child property for child and container. 


e void gtk_container_child_get_property (GtkContainer «container, GtkWidget «child, const gchar 
*property_name, GValue x*value) 


Gets the value of a child property for child and container. 


e void gtk_container_forall (GtkContainer «container, GtkCallback callback, gpointer callback_- 
data) 


Invokes callback on each child of container, including children that are considered "internal" (implementa- 
tion details of the container). 


e void gtk_container_set_in_focus (GtkContainer «container, gboolean enable) 


This setting enables container to get focus always during focus traversal, and moves to sibling container 
instead of passing the focus to its children. 


e void gtk_container_set_force_loop_focus (GtkContainer *container, gboolean loop_focus) 


Enables the forced Loop focus traversal. 
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6.16.2 Function Documentation 
6.16.2.1 void gtk_container_add (GtkContainer « container, GtkWidget « widget) 


Adds widget to container. 


Typically used for simple containers such as GtkWindow, GtkFrame, or GtkButton; for more complicated 
layout containers such as GtkBox or GtkTable, this function will pick default packing parameters that may 
not be correct. So consider functions such as gtk_box_pack_start() and gtk_table_attach() as an alternative 
to gtk_container_add() in those cases. A widget may be added to only one container at a time; you can't 
place the same widget inside two different containers. 

Parameters: 


< container : a GtkContainer 


— widget : a widget to be placed inside container 


Returns: 


void 


6.16.2.2 void gtk_container_add_with_properties (GtkContainer x container, GtkWidget x* widget, 
const gchar « first_prop_name, ...) 
Adds widget to container, setting child properties at the same time. 


See gtk_container_add() and gtk_container_child_set() for more details. 


Parameters: 
< container : a GtkContainer 
— GtkWidget : a widget to be placed inside container 
— first_prop_name : the name of the first child property to set 


— ... : a NULL-terminated list of property names and values, starting with first_prop_name. 


Returns: 


voids 


6.16.2.3 void gtk_container_check_resize (GtkContainer * container) 
Checks resize mode for the container. 


Parameters: 


< container : a GtkContainer 


Returns: 


void 
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6.16.2.4 void gtk_container_child_get (GtkContainer x container, GtkWidget x child, const gchar 
x first_prop_name, ...) 


Gets the values of one or more child properties for child and container. 


Parameters: 
— container : a GtkContainer 
— child : a widget which is a child of container 
— first_prop_name :the name of the first property to get 


— ... : a NULL-terminated list of property names and GValuex, starting with first_prop_name. 


Returns: 


voids 


6.16.2.5 void gtk_container_child_get_property (GtkContainer x container, GtkWidget x child, 
const gchar x property_name, GValue x value) 


Gets the value of a child property for child and container. 


Parameters: 
— container : a GtkContainer 
— child : a widget which is a child of container 
— property_name : the name of the property to get 


— value : a location to return the value 


Returns: 


void 


6.16.2.6 void gtk_container_child_get_valist (GtkContainer « container, GtkWidget x child, const 
gchar x first_property_name, va_list var_args) 


Gets the values of one or more child properties for child and container. 


Parameters: 
— container : a GtkContainer 
— child : a widget which is a child of container 
— first_property_name : the name of the first property to get 


< var_args : a NULL-terminated list of property names and GValuex, starting with first_prop_name. 


Returns: 


void 
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6.16.2.7 void gtk_container_child_set (GtkContainer x container, GtkWidget x child, const gchar + 
first_prop_name, ...) 


Sets one or more child properties for child and container. 


Parameters: 
— container : a GtkContainer 
— child : a widget which is a child of container 
— first_prop_name :the name of the first property to set 


— ... : a NULL-terminated list of property names and values, starting with first_prop_name. 


Returns: 


voids 


6.16.2.8 void gtk_container_child_set_property (GtkContainer x container, GtkWidget « child, 
const gchar x property_name, const GValue x value) 


Sets a child property for child and container. 


Parameters: 
< container : a GtkContainer 
— child : a widget which is a child of container 
— property_name : the name of the property to set 


— value : the value to set the property to 


Returns: 


void 


6.16.2.9 void gtk_container_child_set_valist (GtkContainer x container, GtkWidget « child, const 
gchar x first_property_name, va_list var_args) 


Sets one or more child properties for child and container. 


Parameters: 
— container : a GtkContainer 
— child : a widget which is a child of container 
— first_property_name : the name of the first property to set 


— var_args : a NULL-terminated list of property names and values, starting with first_prop_name. 


Returns: 


void 
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6.16.2.10  GType gtk_container_child_type (GtkContainer x container) 


Returns the type of the children supported by the container. 


Note that this may return G_TYPE_NONE to indicate that no more children can be added, e.g. for a 
GtkPaned which already has two children. 


Parameters: 


< container : a GtkContainer 


Returns: 


a GType. 


6.16.2.11 GParamSpecx gtk_container_class_find_child_property (GObjectClass x cclass, const 
gchar x property_name) 


Finds a child property of a container class by name. 


Parameters: 


— cclass : a GtkContainerClass 


— property_name : the name of the child property to find 


Returns: 


the GParamSpec of the child property or NULL if class has no child property with that name. 


6.16.2.12 void gtk_container_class_install_child_property (GtkContainerClass x cclass, guint 
property_id, GParamSpec x pspec) 


Installs a child property on a container class. 


Parameters: 


<—cclass : a GtkContainerClass 
— property_id : the id for the property 
— pspec : the GParamSpec for the property 


Returns: 


void 


6.16.2.13 GParamSpecx*x gtk_container_class_list_child_properties (GObjectClass x cclass, guint 
x n_properties) 


Returns all child properties of a container class. 


Parameters: 


— cclass : a GtkContainerClass 
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— n_properties : location to return the number of child properties found 


Returns: 


a newly allocated array of GParamSpecx. The array must be freed with g_free(). 


6.16.2.14 void gtk_container_forall (GtkContainer x container, GtkCallback callback, gpointer 
callback_data) 


Invokes callback on each child of container, including children that are considered "internal" (implementa- 
tion details of the container). 


"Internal" children generally weren’t added by the user of the container, but were added by the container 
implementation itself. Most applications should use gtk_container_foreach(), rather than gtk_container_- 
forall(. 


Parameters: 


< container : a GtkContainer 
— callback : a callback 
— callback_data : callback user data 


Returns: 


void 


6.16.2.15 void gtk_container_foreach (GtkContainer « container, GtkCallback callback, gpointer 
callback_data) 
Invokes callback on each non-internal child of container. 


See gtk_container_forall() for details on what constitutes an "internal" child. Most applications should use 
gtk_container_foreach(), rather than gtk_container_forall(). 


Parameters: 


< container : a GtkContainer 
< callback : a callback 
— callback_data : callback user data 


Returns: 


void 


6.16.2.16 guint gtk_container_get_border_width (GtkContainer * container) 


Retrieves the border width of the container. 
See gtk_container_set_border_width(). 
Parameters: 

— container : a GtkContainer 
Returns: 


the current border width 
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6.16.2.17 GList« gtk_container_get_children (GtkContainer x container) 


Returns the container’s non-internal children. 


See gtk_container_forall() for details on what constitutes an "internal" child. 


Parameters: 


< container : a GtkContainer 


Returns: 


a newly-allocated list of the containers non-internal children. 


6.16.2.18 gboolean gtk_container_get_focus_chain (GtkContainer * container, GList «x 
focusable_widgets) 
Retrieves the focus chain of the container, if one has been set explicitly. 


If no focus chain has been explicitly set, GTK+ computes the focus chain based on the positions of the 
children. In that case, GTK+ stores NULL in focusable_widgets and returns FALSE. 


Parameters: 


< container : a GtkContainer 


> focusable_widgets : location to store the focus chain of the container, or NULL. You should free 
this list using g_list_free() when you are done with it, however no additional reference count is 
added to the individual widgets in the focus chain. 


Returns: 


TRUE if the focus chain of the container has been set explicitly. 


6.16.2.19 GtkAdjustmentx gtk_container_get_focus_hadjustment (GtkContainer * container) 


Retrieves the horizontal focus adjustment for the container. 


See gtk_container_set_focus_hadjustment(). 


Parameters: 


< container : a GtkContainer 


Returns: 


the horizontal focus adjustment, or NULL if none has been set. 


6.16.2.20 GtkAdjustment« gtk_container_get_focus_vadjustment (GtkContainer x container) 


Retrieves the vertical focus adjustment for the container. 


See gtk_container_set_focus_vadjustment(). 


Parameters: 


< container : a GtkContainer 
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Returns: 


the vertical focus adjustment, or NULL if none has been set. 


6.16.2.21 GtkResizeMode gtk_container_get_resize_mode (GtkContainer + container) 


Returns the resize mode for the container. 


See gtk_container_set_resize_mode(). 


Parameters: 


< container : a GtkContainer 


Returns: 


the current resize mode 


6.16.2.22 void gtk_container_propagate_expose (GtkContainer x container, GtkWidget x child, 
GdkEventExpose x event) 


When a container receives an expose event, it must send synthetic expose events to all children that don't 
have their own GdkWindows. 


This function provides a convenient way of doing this. A container, when it receives an expose event, 
calls gtk_container_propagate_expose() once for each child, passing in the event the container received. 
gtk_container_propagate_expose() takes care of deciding whether an expose event needs to be sent to the 
child, intersecting the event's area with the child area, and sending the event. In most cases, a container 
can simply either simply inherit the expose implementation from GtkContainer, or, do some drawing and 
then chain to the expose implementation from GtkContainer. 


Parameters: 


< container : a GtkContainer 
— child : a child of container 


— event :a expose event sent to container 


Returns: 


void 


6.16.2.23 void gtk_container_remove (GtkContainer « container, GtkWidget « widget) 


Removes widget from container. 


widget must be inside container. Note that container will own a reference to widget, and that this may be 
the last reference held; so removing a widget from its container can destroy that widget. If you want to 
use widget again, you need to add a reference to it while it’s not inside a container, using g_object_ref(). 
If you don’t want to use widget again it’s usually more efficient to simply destroy it directly using gtk_- 
widget_destroy() since this will remove it from the container and help break any circular reference count 
cycles. 


Parameters: 


< container : a GtkContainer 
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— border_width : a current child of container 


Returns: 


void 


6.16.2.24 void gtk_container_resize_children (GtkContainer * container) 


fn gtk_container_resize_children 


Parameters: 
< container : a GtkContainer 
Returns: 


void 


6.16.2.25 void gtk_container_set_border_width (GtkContainer x container, guint border_width) 


Sets the border width of the container. 


The border width of a container is the amount of space to leave around the outside of the container. The 
only exception to this is GtkWindow; because toplevel windows can’t leave space outside, they leave the 
space inside. The border is added on all sides of the container. To add space to only one side, one approach 
is to create a GtkAlignment widget, call gtk_widget_set_usize() to give it a size, and place it on the side of 
the container as a spacer. 


Parameters: 


< container : a GtkContainer 


— border_width : amount of blank space to leave outside the container. Valid values are in the range 
0-65535 pixels. 


Returns: 


void 


6.16.2.26 void gtk_container_set_focus_chain (GtkContainer * container, GList + 
focusable_widgets) 
Sets a focus chain, overriding the one computed automatically by GTK. 


In principle each widget in the chain should be a descendant of the container, but this is not enforced by this 
method, since it’s allowed to set the focus chain before you pack the widgets, or have a widget in the chain 
that isn’t always packed. The necessary checks are done when the focus chain is actually traversed. 


Parameters: 

< container : a GtkContainer 

— focusable_widgets : the new focus chain. 
Returns: 


void 
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6.16.2.27 void gtk_container_set_focus_child (GtkContainer x container, Gtk Widget x child) 
Sets focus for the container current chaild. 


Parameters: 


< container : a GtkContainer 


— child : a child widget 


Returns: 


void 


6.16.2.28 void gtk_container_set_focus_hadjustment (GtkContainer « container, GtkAdjustment 
* adjustment) 


Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the 
adjustment is scrolled to show that widget. 


This function sets the horizontal alignment. See gtk_scrolled_window_get_hadjustment() for a typical way 
of obtaining the adjustment and gtk_container_set_focus_vadjustment() for setting the vertical adjustment. 
The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate 
children of the container. 


Parameters: 


< container : a GtkContainer 


— adjustment : an adjustment which should be adjusted when the focus is moved among the descen- 
dents of container 


Returns: 


void 


6.16.2.29 void gtk_container_set_focus_vadjustment (GtkContainer x container, GtkAdjustment x 
adjustment) 


Hooks up an adjustment to focus handling in a container, so when a child of the container is focused, the 
adjustment is scrolled to show that widget. 


This function sets the vertical alignment. See gtk_scrolled_window_get_vadjustment() for a typical way of 
obtaining the adjustment and gtk_container_set_focus_hadjustment() for setting the horizontal adjustment. 
The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate 
children of the container. 


Parameters: 


< container : a GtkContainer 


< adjustment : an adjustment which should be adjusted when the focus is moved among the descen- 
dents of container 


Returns: 


void 
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6.16.2.30 void gtk_container_set_force_loop_focus (GtkContainer * container, gboolean 
loop_focus) 
Enables the forced Loop focus traversal. 


If Loop focus is enabled, Container always passes the focus to children, and never keeps the focus itself. 


Parameters: 

text_view [in] a GtkTextView 

loop_focus [in] TRUE to enable Loop focus. 
Returns: 

void 
See also: 


gtk_container_set_in_focus 


Since 


LIMO R1 


6.16.2.31 void gtk_container_set_in_focus (GtkContainer x container, gboolean enable) 


This setting enables container to get focus always during focus traversal, and moves to sibling container 
instead of passing the focus to its children. 
Parameters: 


text_view [in] a GtkTextView 


enable [in] TRUE to enable the Container focus always. 
Returns: 

void 
See also: 


gtk_container_set_force_loop_focus 


Since 


LIMO R1 


6.16.2.32 void gtk_container_set_reallocate_redraws (GtkContainer x container, gboolean 
needs_redraws) 
Sets the reallocate_redraws flag of the container to the given value. 


Containers requesting reallocation redraws get automatically redrawn if any of their children changed al- 
location. 


Parameters: 


< container : a GtkContainer 
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— needs_redraws : the new value for the container’s reallocate_redraws flag. 


Returns: 


void 


6.16.2.33 void gtk_container_set_resize_mode (GtkContainer * container, GtkResizeMode 
resize_mode) 


Sets the resize mode for the container. 


The resize mode of a container determines whether a resize request will be passed to the container’s parent, 
queued for later execution or executed immediately. 


Parameters: 


< container : a GtkContainer 


— border_width : the new resize mode. 


Returns: 


void 


6.16.2.34 void gtk_container_unset_focus_chain (GtkContainer x container) 


Removes a focus chain explicitly set with gtk_container_set_focus_chain(). 


Parameters: 


< container : a GtkContainer 


Returns: 


void 
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6.17 GtkItem 


6.17.1 Detailed Description 


The GtkItem widget is an abstract base class for GtkMenultem, GtkListltem and GtkTreeltem. 


Data Structures 


e struct _Gtkltem 


Gtkltem instance structure. 


e struct _GtkItemClass 


GtkItem instance class structure. 


Functions 


e void gtk_item_select (GtkItem *item) 


Emits the "select" signal on the given item. 


e void gtk_item_deselect (GtkItem xitem) 


Emits the "deselect" signal on the given item. 


e void gtk_item_toggle (GtkItem *item) 


Emits the "toggle" signal on the given item. 


6.17.2 Function Documentation 
6.17.2.1 void gtk_item_deselect (GtkItem x item) 


Emits the "deselect" signal on the given item. 


Parameters: 


item [in] a GtkItem. 


Returns: 


void 


6.17.2.2 void gtk_item_select (GtkItem x item) 


Emits the "select" signal on the given item. 


Parameters: 
item [in] a GtkItem. 


Returns: 


void 
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6.17.2.3 void gtk_item_toggle (GtkItem x item) 


Emits the "toggle" signal on the given item. 


Parameters: 


item [in] a GtkItem. 


Returns: 


void 
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6.18 GtkMisc 


6.18.1 Detailed Description 


The GtkMisc widget is an abstract widget which is not useful itself, but is used to derive subclasses which 
have alignment and padding attributes. 


The horizontal and vertical padding attributes allows extra space to be added around the widget. 


The horizontal and vertical alignment attributes enable the widget to be positioned within its allocated area. 
Note that 1f the widget is added to a container in such a way that it expands automatically to fill its allocated 
area, the alignment settings will not alter the widgets position. 


Data Structures 


e struct _GtkMisc 


GtkMisc interface structure. 


e struct _GtkMiscClass 


GtkMisc interface class structure. 


Functions 


e GType gtk_misc_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


e void gtk_misc_set_alignment (GtkMisc *misc, gfloat xalign, gfloat yalign) 


Sets the alignment of the widget. 


e void gtk_misc_get_alignment (GtkMisc «misc, gfloat *xalign, gfloat *yalign) 


Sets the alignment of the widget. 


e void gtk_misc_set_padding (GtkMisc *misc, gint xpad, gint ypad) 


Sets the alignment of the widget. 


e void gtk_misc_get_padding (GtkMisc «misc, gint *xpad, gint *ypad) 


Sets the alignment of the widget. 


6.18.2 Function Documentation 
6.18.2.1 void gtk_misc_get_alignment (GtkMisc x misc, gfloat x xalign, gfloat x yalign) 


Sets the alignment of the widget. 


See gtk_misc_set_alignment(). 


Parameters: 


misc [in] a GtkMisc. 
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xalign [out] location to store X alignment of misc, or NULL 


yalign [out] location to store Y alignment of misc, or NULL 


Returns: 


void 


6.18.2.2 void gtk_misc_get_padding (GtkMisc x misc, gint * xpad, gint * ypad) 


Sets the alignment of the widget. 


See gtk_misc_set_padding(). 


Parameters: 
misc [in] The text you want the GtkLabel to hold. 
xalign [out] location to store padding in the X direction, or NULL 


yalign [out] location to store padding in the Y direction, or NULL 


Returns: 


void 


6.18.2.3 GType gtk_misc_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


6.18.2.4 void gtk_misc_set_alignment (GtkMisc x misc, gfloat xalign, gfloat yalign) 


Sets the alignment of the widget. 


Parameters: 
misc [in] a GtkMisc. 
xalign [in] the horizontal alignment, from 0 (left) to 1 (right).. 


yalign [in] the vertical alignment, from 0 (top) to 1 (bottom).. 


Returns: 


void 
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6.18.2.5 void gtk_misc_set_padding (GtkMisc « misc, gint xpad, gint ypad) 
Sets the alignment of the widget. 


Parameters: 
misc [in] a GtkMisc. 
xalign [in] the amount of space to add on the left and right of the widget, in pixels. 


yalign [in] the amount of space to add on the top and bottom of the widget, in pixels. 


Returns: 


void 
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6.19 GtkScale 


6.19.1 Detailed Description 


A GtkScale is a slider control used to select a numeric value. 


To use it, you’ll probably want to investigate the methods on its base class, GtkRange, in addition to the 
methods for GtkScale itself. To set the value of a scale, you would normally use gtk_range_set_value(). To 
detect changes to the value, you would normally use the "value_changed" signal. 


The GtkScale widget is an abstract class, used only for deriving the subclasses GtkHScale and GtkV Scale. 
To create a scale widget, call gtk_hscale_new_with_range() or gtk_vscale_new_with_range(). 


Slide sample 


Figure 6.1: GtkScale 


Data Structures 


e struct _GtkScale 


GtkScale instance structure. 


e struct _GtkScaleClass 


GtkScale instance class structure. 


Functions 


e void gtk_scale_set_digits (GtkScale xscale, gint digits) 
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Sets the number of decimal places that are displayed in the value. 


e gint gtk_scale_get_digits (GtkScale *scale) 


Gets the number of decimal places that are displayed in the value. 


e void gtk_scale_set_draw_value (GtkScale «scale, gboolean draw_value) 


Specifies whether the current value is displayed as a string next to the slider. 


e gboolean gtk_scale_get_draw_value (GtkScale x*scale) 


Returns whether the current value is displayed as a string next to the slider. 


e void gtk_scale_set_value_pos (GtkScale «scale, GtkPositionType pos) 


Sets the position in which the current value is displayed. 


e GtkPositionType gtk_scale_get_value_pos (GtkScale *scale) 


Gets the position in which the current value is displayed. 


e PangoLayout « gtk_scale_get_layout (GtkScale «scale) 
Gets the PangoLayout used to display the scale. 


e void gtk_scale_get_layout_offsets (GtkScale «scale, gint *x, gint xy) 


Obtains the coordinates where the scale will draw the PangoLayout representing the text in the scale. 


6.19.2 Function Documentation 
6.19.2.1 gint gtk_scale_get_digits (GtkScale x scale) 


Gets the number of decimal places that are displayed in the value. 


Parameters: 


scale [in] a GtkScale 


Returns: 


the number of decimal places that are displayed. 


6.19.2.2 gboolean gtk_scale_get_draw_value (GtkScale x scale) 


Returns whether the current value is displayed as a string next to the slider. 


Parameters: 


scale [in] a GtkScale 


Returns: 


whether the current value is displayed as a string 
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6.19.2.3 PangoLayout* gtk_scale_get_layout (GtkScale x scale) 


Gets the PangoLayout used to display the scale. 


The returned object is owned by the scale so does not need to be freed by the caller. 


Parameters: 


scale [in] a GtkScale 


Returns: 


the PangoLayout for this scale, or NULL if the draw_value property is FALSE. 


6.19.2.4 void gtk_scale_get_layout_offsets (GtkScale x scale, gint « x, gint x y) 


Obtains the coordinates where the scale will draw the PangoLayout representing the text in the scale. 


Remember when using the PangoLayout function you need to convert to and from pixels using PANGO_- 
PIXELS() or PANGO_SCALE. 


If the draw_value property is FALSE, the return values are undefined. 


Parameters: 


scale [in] a GtkScale 
x [out] location to store X offset of layout, or NULL 
y [out] location to store Y offset of layout, or NULL 


Returns: 


void 


Note: 


: If the draw_value property of gtk_scale_set_draw_value is FALSE, the return values are undefined. 


6.19.2.5 GtkPositionType gtk_scale_get_value_pos (GtkScale « scale) 


Gets the position in which the current value is displayed. 


Parameters: 


scale [in] a GtkScale 


Returns: 


the position in which the current value is displayed 


6.19.2.6 void gtk_scale_set_digits (GtkScale x scale, gint digits) 


Sets the number of decimal places that are displayed in the value. 


Also causes the value of the adjustment to be rounded off to this number of digits, so the retrieved value 
matches the value the user saw. 
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Parameters: 


scale [in] a GtkScale 


digits [in] the number of decimal places to display, e.g. use 1 to display 1.0, 2 to display 1.00 etc. 


Returns: 


void 


6.19.2.7 void gtk_scale_set_draw_value (GtkScale « scale, gboolean draw_value) 


Specifies whether the current value is displayed as a string next to the slider. 


Parameters: 


scale [in] a GtkScale 


draw_value [in] a boolean. 


Returns: 


void 


6.19.2.8 void gtk_scale_set_value_pos (GtkScale « scale, GtkPositionType pos) 


Sets the position in which the current value is displayed. 


Parameters: 


scale [in] a GtkScale 


pos [in] the position in which the current value is displayed 


Returns: 


void 
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6.20 GtkScrollBar 


6.20.1 Detailed Description 


The GtkScrollbar widget is an abstract base class for GtkHScrollbar and GtkVScrollbar. 
It is not very useful in itself. 


The position of the thumb in a scrollbar is controlled by the scroll adjustments. See GtkAdjustment for the 
fields in an adjustment - for GtkScrollbar, the "value" field represents the position of the scrollbar, which 
must be between the "lower" field and "upper - page_size." The "page_size" field represents the size of the 
visible scrollable area. The "step_increment" and "page_increment" fields are used when the user asks to 
step down (using the small stepper arrows) or page down (using for example the PageDown key). 


Data Structures 


e struct _GtkScrollbar 


GtkScrollbar instance structure. 


e struct _GtkScrollbarClass 


GtkScrollbar instance class structure. 
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6.21 GtkRange 


6.21.1 Detailed Description 


Base class for widgets which visualize an adjustment. 


Data Structures 


e struct _GtkRange 


GtkRange instance structure. 


e struct _GtkRangeClass 


GtkRange instance class structure. 


Functions 


e void gtk_range_set_update_policy (GtkRange range, GtkUpdateType policy) 


Sets the update policy for the range. 


e GtkUpdateType gtk_range_get_update_policy (GtkRange +range) 


Gets the update policy of range. 


e void gtk_range_set_adjustment (GtkRange *range, GtkAdjustment *adjustment) 


Sets the adjustment to be used as the "model" object for this range widget. 


e GtkAdjustment x gtk_range_get_adjustment (GtkRange x*range) 
Get the GtkAdjustment which is the "model" object for GtkRange. 


e void gtk_range_set_inverted (GtkRange «range, gboolean setting) 


Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. 


e gboolean gtk_range_get_inverted (GtkRange *range) 


Gets the value set by gtk_range_set_inverted(). 


e void gtk_range_set_lower_stepper_sensitivity (GtkRange «range, GtkSensitivityType sensitivity) 


Sets the sensitivity policy for the stepper that points to the ’lower’ end of the GtkRange’s adjustment. 


e GtkSensitivityType gtk_range_get_lower_stepper_sensitivity (GtkRange range) 


Gets the sensitivity policy for the stepper that points to the ‘lower’ end of the GtkRange’s adjustment. 


e void gtk_range_set_upper_stepper_sensitivity (GtkRange *range, GtkSensitivityType sensitivity) 


Sets the sensitivity policy for the stepper that points to the ‘upper’ end of the GtkRange’s adjustment. 


e GtkSensitivityType gtk_range_get_upper_stepper_sensitivity (GtkRange *range) 
Gets the sensitivity policy for the stepper that points to the ‘upper’ end of the GtkRange’s adjustment. 


e void gtk_range_set_increments (GtkRange *range, gdouble step, gdouble page) 


Sets the step and page sizes for the range. 
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e void gtk_range_set_range (GtkRange *range, gdouble min, gdouble max) 


Sets the allowable values in the GtkRange, and clamps the range value to be between min and max. 


e void gtk_range_set_value (GtkRange *range, gdouble value) 


Sets the current value of the range; if the value is outside the minimum or maximum range values, it will be 
clamped to fit inside them. 


e gdouble gtk_range_get_value (GtkRange *range) 


Gets the current value of the range. 


6.21.2 Function Documentation 
6.21.2.1 GtkAdjustment« gtk_range_get_adjustment (GtkRange + range) 


Get the GtkAdjustment which is the "model" object for GtkRange. 


See gtk_range_set_adjustment() for details. The return value does not have a reference added, so should 
not be unreferenced. 


Parameters: 


range [in] a GtkRange 


Returns: 


a GtkAdjustment 


6.21.2.2 gboolean gtk_range_get_inverted (GtkRange x range) 
Gets the value set by gtk_range_set_inverted(). 


Parameters: 


range [in] a GtkRange 


Returns: 


TRUE if the range is inverted 


6.21.2.3 GtkSensitivityType gtk_range_get_lower_stepper_sensitivity (GtkRange « range) 


Gets the sensitivity policy for the stepper that points to the lower’ end of the GtkRange’s adjustment. 


Parameters: 


range [in] a GtkRange 


Returns: 


The lower stepper’s sensitivity policy. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.21 GtkRange 155 


6.21.2.4 GtkUpdateType gtk_range_get_update_policy (GtkRange x range) 


Gets the update policy of range. 


See gtk_range_set_update_policy(). 


Parameters: 


range [in] a GtkRange 


Returns: 


the current update policy 


6.21.2.5  GtkSensitivityType gtk_range_get_upper_stepper_sensitivity (GtkRange x range) 


Gets the sensitivity policy for the stepper that points to the ’upper’ end of the GtkRange’s adjustment. 


Parameters: 


range [in] a GtkRange 


Returns: 


The upper stepper’s sensitivity policy. 


6.21.2.6 gdouble gtk_range_get_value (GtkRange x range) 
Gets the current value of the range. 


Parameters: 


range [in] a GtkRange 


Returns: 


current value of the range. 


6.21.2.7 void gtk_range_set_adjustment (GtkRange « range, GtkAdjustment « adjustment) 


Sets the adjustment to be used as the "model" object for this range widget. 


The adjustment indicates the current range value, the minimum and maximum range values, the step/page 
increments used for keybindings and scrolling, and the page size. The page size is normally 0 for GtkScale 
and nonzero for GtkScrollbar, and indicates the size of the visible area of the widget being scrolled. The 
page size affects the size of the scrollbar slider. 


Parameters: 
range [in] a GtkRange 
adjustment [in] a GtkAdjustment 
Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


156 Module Documentation 


6.21.2.8 void gtk_range_set_increments (GtkRange x range, gdouble step, gdouble page) 


Sets the step and page sizes for the range. 
The step size is used when the user clicks the GtkScrollbar arrows or moves GtkScale via arrow keys. The 
page size is used for example when moving via Page Up or Page Down keys. 
Parameters: 
range [in] a GtkRange 
step [in] step size 


page [in] page size 


Returns: 


void 


6.21.2.9 void gtk_range_set_inverted (GtkRange x range, gboolean setting) 


Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. 


Inverted ranges have higher values at the top or on the right rather than on the bottom or left. 


Parameters: 
range [in] a GtkRange 
setting [in] TRUE to invert the range 


Returns: 


void 


6.21.2.10 void gtk_range_set_lower_stepper_sensitivity (GtkRange « range, GtkSensitivity Type 
sensitivity) 


Sets the sensitivity policy for the stepper that points to the *lower” end of the GtkRange’s adjustment. 


Parameters: 
range [in] a GtkRange 


sensitivity [in] the lower stepper’s sensitivity policy. 


Returns: 


void 


6.21.2.11 void gtk_range_set_range (GtkRange * range, gdouble min, gdouble max) 


Sets the allowable values in the GtkRange, and clamps the range value to be between min and max. 


(If the range has a non-zero page size, it is clamped between min and max - page-size.) 
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Parameters: 
range [in] a GtkRange 
min [in] minimum range value 


max [in] maximum range value 


Returns: 


void 


6.21.2.12 void gtk_range_set_update_policy (GtkRange x range, GtkUpdateType policy) 


Sets the update policy for the range. 


GTK_UPDATE_CONTINUOUS means that anytime the range slider is moved, the range value will change 
and the value_changed signal will be emitted. GTK_UPDATE_DELAYED means that the value will be 
updated after a brief timeout where no slider motion occurs, so updates are spaced by a short time rather 
than continuous. GTK_UPDATE_DISCONTINUOUS means that the value will only be updated when the 
user releases the button and ends the slider drag operation. 
Parameters: 

range [in] a GtkRange 

policy [in] update policy 


Returns: 


void 


6.21.2.13 void gtk_range_set_upper_stepper_sensitivity (GtkRange x range, GtkSensitivityType 
sensitivity) 


Sets the sensitivity policy for the stepper that points to the ’upper’ end of the GtkRange’s adjustment. 


Parameters: 

range [in] a GtkRange 

sensitivity [in] the upper stepper’s sensitivity policy. 
Returns: 


void 


6.21.2.14 void gtk_range_set_value (GtkRange x range, gdouble value) 


Sets the current value of the range; if the value is outside the minimum or maximum range values, it will 
be clamped to fit inside them. 


The range emits the "value_changed" signal if the value changes. 


Parameters: 


range [in] a GtkRange 
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value [in] new value of the range 


Returns: 


void 
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6.22 GtkWidget 


6.22.1 Detailed Description 


GtkWidget is Base class for all GTK Widgets, GtkWidget introduces style properties - these are basically 
object properties that are stored not on the object, but in the style object associated to the widget. 


Style properties are set in resource files. This mechanism is used for configuring such things as the location 
of the scrollbar arrows through the theme, giving theme authors more control over the look of applications 
without the need to write a theme engine in C. 


Use gtk_widget_class_install_style_property() to install style properties for a widget class, gtk_widget_- 
class_find_style_property() or gtk_widget_class_list_style_properties() to get information about existing 
style properties and gtk_widget_style_get_property(), gtk_widget_style_get() or gtk_widget_style_get_- 
valist() to obtain the value of a style property. 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkRequisition 


A requisition is a desired amount of space which a widget may request. 


e struct _GtkWidget 


The widget is the base of the tree for displayable objects. 


Functions 


e GtkWidget x gtk _widget_new (GType type, const gchar »first_property_name.,...) 


This is a convenience function for creating a widget and setting its properties in one go. 


GtkWidget x gtk_widget_ref (GtkWidget «widget) 


Adds a reference to a widget. 


void gtk_widget_unref (GtkWidget *widget) 


Decrements a reference to a widget. 


void gtk_widget_destroy (GtkWidget *widget) 


Destroys a widget. 


void gtk_widget_destroyed (GtkWidget «widget, GtkWidget **widget_pointer) 
This function sets *widget_pointer to NULL if widget_pointer != NULL. 


void gtk_widget_unparent (GtkWidget «widget) 


This function is only for use in widget implementations. 


void gtk_widget_show (GtkWidget *widget) 
Flags a widget to be displayed. 
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void gtk_widget_show_now (GtkWidget *widget) 


Shows a widget. 


void gtk_widget_hide (GtkWidget *widget) 


Reverses the effects of gtk_widget_show(), causing the widget to be hidden (invisible to the user). 


void gtk_widget_show_all (GtkWidget *widget) 


Recursively shows a widget, and any child widgets (if the widget is a container). 


void gtk_widget_hide_all (GtkWidget *widget) 


Recursively hides a widget and any child widgets. 


void gtk_widget_set_no_show_all (GtkWidget *widget, gboolean no_show_all) 


Sets the "no_show_all" property, which determines whether calls to gtk_widget_show_all() and gtk_- 
widget_hide_all() will affect this widget. 


gboolean gtk_widget_get_no_show_all (GtkWidget *widget) 


Returns the current value of the "no_show_all" property, which determines whether calls to gtk_widget_- 
show_all() and gtk_widget_hide_all() will affect this widget. 


void gtk_widget_map (GtkWidget *widget) 


This function is only for use in widget implementations. 


void gtk_widget_unmap (GtkWidget *widget) 


This function is only for use in widget implementations. 


void gtk_widget_realize (GtkWidget *widget) 


Creates the GDK (windowing system) resources associated with a widget. 


void gtk_widget_unrealize (GtkWidget *widget) 


This function is only useful in widget implementations. 


void gtk_widget_queue_draw (GtkWidget *widget) 


Equivalent to calling gtk_widget_queue_draw_area() for the entire area of a widget. 


void gtk_widget_queue_draw_area (GtkWidget «widget, gint x, gint y, gint width, gint height) 


Invalidates the rectangular area of widget defined by x, y, width and height by calling gdk_window_- 
invalidate_rect() on the widget’s window and all its child windows. 


void gtk_widget_queue_resize (GtkWidget *widget) 


This function is only for use in widget implementations. 


void gtk_widget_queue_resize_no_redraw (GtkWidget *widget) 


Flags a widget to have its size renegotiated; should be called when a widget for some reason has a new size 
request. 


void gtk_widget_size_request (GtkWidget «widget, GtkRequisition *requisition) 


This function is typically used when implementing a GtkContainer subclass. 
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e void gtk_widget_size_allocate (GtkWidget «widget, GtkAllocation x*allocation) 


This function is only used by GtkContainer subclasses, to assign a size and position to their child widgets. 


e void gtk_widget_get_child_requisition (GtkWidget «widget, GtkRequisition *requisition) 


This function is only for use in widget implementations. 


e void gtk_widget_add_accelerator (GtkWidget *widget, const gchar *accel_signal, GtkAccelGroup 
*accel_group, guint accel_key, GdkModifierType accel_mods, GtkAccelFlags accel_flags) 


Installs an accelerator for this widget in accel_group that causes accel_signal to be emitted if the acceler- 
ator is activated. 


e gboolean gtk _widget_remove_accelerator (GtkWidget *widget, GtkAccelGroup *accel_group, 
guint accel_key, GdkModifierType accel_mods) 


Removes an accelerator from widget, previously installed with gtk_widget_add_accelerator(). 


e void gtk _widget_set_accel_path (GtkWidget «widget, const gchar *accel_path, GtkAccelGroup 
*accel_group) 


Given an accelerator group, accel_group, and an accelerator path, accel_path, sets up an accelerator in 
accel_group so whenever the key binding that is defined for accel_path is pressed, widget will be activated. 


e GList x gtk_widget_list_accel_closures (GtkWidget *widget) 


Lists the closures used by widget for accelerator group connections with gtk_accel_group_connect_by_- 
path() or gtk_accel_group_connect(). 


e gboolean gtk_widget_can_activate_accel (GtkWidget «widget, guint signal_id) 


Determines whether an accelerator that activates the signal identified by signal_id can currently be acti- 
vated. 


e gboolean gtk_widget_mnemonic_activate (GtkWidget «widget, gboolean group_cycling) 


[Deprecated] Activates the widget mnemonic 


e gboolean gtk_widget_event (GtkWidget «widget, GdkEvent xevent) 


This function is used to emit the event signals on a widget (those signals should never be emitted without 
using this function to do so). 


e gint gtk_widget_send_expose (GtkWidget «widget, GdkEvent *event) 


Very rarely-used function. 


e gboolean gtk_widget_activate (GtkWidget *widget) 


For widgets that can be "activated" (buttons, menu items, etc. 


e gboolean gtk _widget_set_scroll_adjustments (GtkWidget «widget, GtkAdjustment *hadjustment, 
GtkAdjustment *vadjustment) 


For widgets that support scrolling, sets the scroll adjustments and returns TRUE. 


e void gtk_widget_reparent (GtkWidget «widget, GtkWidget *new_parent) 


Moves a widget from one GtkContainer to another, handling reference count issues to avoid destroying the 
widget. 


e gboolean gtk _widget_intersect (GtkWidget widget, GdkRectangle xarea, GdkRectangle 
*intersection) 
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Computes the intersection of a widget's area and area, storing the intersection in intersection, and returns 
TRUE ¡f there was an intersection. 


GdkRegion * gtk_widget_region_intersect (GtkWidget *widget, GdkRegion *region) 


Computes the intersection of a widget’s area and region, returning the intersection. 


void gtk_widget_freeze_child_notify (GtkWidget «widget) 


Stops emission of "child-notify" signals on widget. 


void gtk_widget_child_notify (GtkWidget «widget, const gchar *child_property) 
Emits a "child-notify" signal for the child property child_property on widget. 


void gtk_widget_thaw_child_notify (GtkWidget «widget) 


Reverts the effect of a previous call to gtk_widget_freeze_child_notify(). 


gboolean gtk_widget_is_focus (GtkWidget *widget) 


Determines if the widget is the focus widget within its toplevel. 


void gtk_widget_grab_focus (GtkWidget «widget) 
Causes widget to have the keyboard focus for the GtkWindow it’s inside. 


void gtk_widget_grab_default (GtkWidget *widget) 


Causes widget to become the default widget. 


void gtk_widget_set_name (GtkWidget «widget, const gchar xname) 


Widgets can be named, which allows you to refer to them from a gtkrc file. 


G_CONST_RETURN gchar x gtk_widget_get_name (GtkWidget *widget) 


Retrieves the name of a widget. 


void gtk_widget_set_state (GtkWidget «widget, GtkStateType state) 


This function is for use in widget implementations. 


void gtk_widget_set_sensitive (GtkWidget «widget, gboolean sensitive) 


Sets the sensitivity of a widget. 


void gtk_widget_set_app_paintable (GtkWidget «widget, gboolean app_paintable) 


Sets whether the application intends to draw on the widget in an expose-event handler. 


void gtk_widget_set_double_buffered (GtkWidget *widget, gboolean double_buffered) 


Widgets are double buffered by default; you can use this function to turn off the buffering. 


void gtk_widget_set_redraw_on_allocate (GtkWidget «widget, gboolean redraw_on_allocate) 


Sets whether the entire widget is queued for drawing when its size allocation changes. 


void gtk_widget_set_parent (GtkWidget «widget, GtkWidget x*parent) 


This function is useful only when implementing subclasses of GtkContainer. 


void gtk_widget_set_parent_window (GtkWidget «widget, GdkWindow *parent_window) 


Sets anon default parent window for widget. 
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e void gtk_widget_set_child_visible (GtkWidget *widget, gboolean is_visible) 


Sets whether widget should be mapped along with its when its parent is mapped and widget has been shown 
with gtk_widget_show(). 


e gboolean gtk_widget_get_child_visible (GtkWidget x*widget) 


Gets the value set with gtk_widget_set_child_visible(). 


e GtkWidget * gtk_widget_get_parent (GtkWidget *widget) 


Returns the parent container of widget. 


e GdkWindow x gtk _widget_get_parent_window (GtkWidget *widget) 


Gets widget’s parent window. 


e gboolean gtk_widget_child_focus (GtkWidget «widget, GtkDirectionType direction) 
Causes widget to have the keyboard focus for the GtkWindow child. 


e void gtk_widget_set_size_request (GtkWidget «widget, gint width, gint height) 


Sets the minimum size of a widget; that is, the widget’s size request will be width by height. 


e void gtk_widget_get_size_request (GtkWidget «widget, gint «width, gint xheight) 


Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request(). 


e void gtk_widget_set_events (GtkWidget «widget, gint events) 
Sets the event mask (see GdkEventMask) for a widget. 


e void gtk_widget_add_events (GtkWidget «widget, gint events) 


Adds the events in the bitfield events to the event mask for widget. 


e void gtk_widget_set_extension_events (GtkWidget «widget, GdkExtensionMode mode) 


Sets the extension events mask to mode. 


e GdkExtensionMode gtk_widget_get_extension_events (GtkWidget *widget) 


Retrieves the extension events the widget will receive;. 


e GtkWidget x gtk_widget_get_toplevel (GtkWidget *widget) 


This function returns the topmost widget in the container hierarchy widget is a part of. 


e GtkWidget x gtk_widget_get_ancestor (GtkWidget «widget, GType widget_type) 


Gets the first ancestor of widget with type widget_type. 


e GdkColormap * gtk_widget_get_colormap (GtkWidget *widget) 


Gets the colormap that will be used to render widget. 


e GdkVisual x gtk_widget_get_visual (GtkWidget *«widget) 


Gets the visual that will be used to render widget. 


e GdkScreen * gtk_widget_get_screen (GtkWidget *widget) 


Get the GdkScreen from the toplevel window associated with this widget. 
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gboolean gtk_widget_has_screen (GtkWidget «widget) 


Checks whether there is a GdkScreen is associated with this widget. 


GdkDisplay * gtk_widget_get_display (GtkWidget *widget) 


Get the GdkDisplay for the toplevel window associated with this widget. 


GdkWindow x gtk_widget_get_root_window (GtkWidget *widget) 


Get the GdkDisplay for the toplevel window associated with this widget. 


GtkSettings * gtk _widget_get_settings (GtkWidget «widget) 
Gets the settings object holding the settings (global property settings, RC file information, etc) used for this 
widget. 

GtkClipboard * gtk_widget_get_clipboard (GtkWidget «widget, GdkAtom selection) 


Returns the clipboard object for the given selection to be used with widget. 


void gtk_widget_set_colormap (GtkWidget «widget, GdkColormap *colormap) 


The following functions must not be called on an already realized widget. 


gint gtk_widget_get_events (GtkWidget *widget) 


Returns the event mask for the widget (a bitfield containing flags from the GdkEventMask enumeration). 


void gtk_widget_get_pointer (GtkWidget «widget, gint «x, gint xy) 


Obtains the location of the mouse pointer in widget coordinates. 


gboolean gtk_widget_is_ancestor (GtkWidget «widget, GtkWidget *ancestor) 


Determines whether widget is somewhere inside ancestor, possibly with intermediate containers. 


gboolean gtk_widget_translate_coordinates (GtkWidget *src_widget, GtkWidget *dest_widget, gint 
src_x, gint src_y, gint *dest_x, gint *dest_y) 


Translate coordinates relative to src_widget’s allocation to coordinates relative to dest_widget’s alloca- 
tions. 


gboolean gtk_widget_hide_on_delete (GtkWidget *widget) 


Utility function; intended to be connected to the "delete_event" signal on a GtkWindow. 


void gtk_widget_set_style (GtkWidget «widget, GtkStyle x*style) 
Sets the GtkStyle for a widget (widget->style). 


void gtk_widget_ensure_style (GtkWidget «widget) 
Ensures that widget has a style (widget->style). 


GtkStyle x gtk_widget_get_style (GtkWidget *widget) 


Simply an accessor function that returns widget->style. 


void gtk_widget_modify_style (GtkWidget «widget, GtkRcStyle xstyle) 
Modifies style values on the widget. 


GtkRcStyle x gtk_widget_get_modifier_style (GtkWidget *widget) 


Returns the current modifier style for the widget. 
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e void gtk_widget_modify_fg (GtkWidget «widget, GtkStateType state, const GdkColor *color) 


Sets the foreground color for a widget in a particular state. 


e void gtk_widget_modify_bg (GtkWidget «widget, GtkStateType state, const GdkColor color) 


Sets the background color for a widget in a particular state. 


e void gtk_widget_modify_text (GtkWidget «widget, GtkStateType state, const GdkColor color) 


Sets the text color for a widget in a particular state. 


e void gtk_widget_modify_base (GtkWidget «widget, GtkStateType state, const GdkColor *color) 


Sets the base color for a widget in a particular state. 


e void gtk_widget_modify_font (GtkWidget «widget, PangoFontDescription *font_desc) 


Sets the font to use for a widget. 


e PangoContext x gtk_widget_create_pango_context (GtkWidget *«widget) 


Creates a new PangoContext with the appropriate font map, font description, and base direction for drawing 
text for this widget. 


e PangoContext * gtk_widget_get_pango_context (GtkWidget «widget) 


Gets a PangoContext with the appropriate font map, font description, and base direction for this widget. 


e PangoLayout * gtk_widget_create_pango_layout (GtkWidget «widget, const gchar xtext) 


Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing 
text for this widget. 


e GdkPixbuf x gtk _widget_render_icon (GtkWidget «widget, const gchar x*stock_id, GtkIconSize size, 
const gchar detail) 


A convenience function that uses the theme engine and RC file settings for widget to look up stock_id and 
render it to a pixbuf. 


e void gtk_widget_set_composite_name (GtkWidget «widget, const gchar xname) 


Sets a widgets composite name. 


e gchar * gtk_widget_get_composite_name (GtkWidget «widget) 


Obtains the composite name of a widget. 


e void gtk_widget_reset_rc_styles (GtkWidget «widget) 


Reset the styles of widget and all descendents, so when they are looked up again, they get the correct values 
for the currently loaded RC file settings. 


e void gtk_widget_push_colormap (GdkColormap *cmap) 


Pushes cmap onto a global stack of colormaps; the topmost colormap on the stack will be used to create all 
widgets. 


e void gtk_widget_push_composite_child (void) 
Makes all newly-created widgets as composite children until the corresponding gtk_widget_pop_- 


composite_child() call. 


e void gtk_widget_pop_composite_child (void) 
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Cancels the effect of a previous call to gtk_widget_push_composite_child(). 


void gtk_widget_pop_colormap (void) 


Removes a colormap pushed with gtk_widget_push_colormap(). 


void gtk_widget_class_install_style_property (GtkWidgetClass *klass, GParamSpec *pspec) 


Installs a style property on a widget class. 


void gtk_widget_class_install_style_property_parser (GtkWidgetClass *klass, GParamSpec *pspec, 
GtkRcPropertyParser parser) 


Installs a style property on a widget class. 


GParamSpec x gtk _widget_class_find_style_property (GtkWidgetClass x*klass, const gchar 
*property_name) 


Finds a style property of a widget class by name. 


GParamSpec ** gtk widget_class_list_style_properties (GtkWidgetClass klass, guint *n_- 
properties) 


Returns all style properties of a widget class. 


void gtk _widget_style_get_property (GtkWidget «widget, const gchar *property_name, GValue 
*value) 


Gets the value of a style property of widget. 


void gtk_widget_style_get_valist (GtkWidget *widget, const gchar x*first_property_name, va_list 
var_args) 


Non-vararg variant of gtk_widget_style_get(). 


void gtk_widget_style_get (GtkWidget «widget, const gchar «first_property_name,...) G_GNUC_- 
NULL_TERMINATED 


Gets the values of a multiple style properties of widget. 


void gtk_widget_set_default_colormap (GdkColormap *colormap) 


Sets the default colormap to use when creating widgets. 


GtkStyle * gtk_widget_get_default_style (void) 


Returns the default style used by all widgets initially. 


GdkColormap * gtk_widget_get_default_colormap (void) 


Obtains the default colormap used to create widgets. 


GdkVisual * gtk _widget_get_default_visual (void) 


Obtains the visual of the default colormap. 


void gtk_widget_set_direction (GtkWidget «widget, GtkTextDirection dir) 


Sets the reading direction on a particular widget. 


GtkTextDirection gtk_widget_get_direction (GtkWidget «widget) 


Gets the reading direction for a particular widget. 
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e void gtk_widget_set_default_direction (GtkTextDirection dir) 


Sets the default reading direction for widgets where the direction has not been explicitly set by gtk_widget_- 
set_direction(). 


e GtkTextDirection gtk_widget_get_default_direction (void) 


Obtains the current default reading direction. 


e gboolean gtk_widget_is_composited (GtkWidget *widget) 


Whether widget can rely on having its alpha channel drawn correctly. 


e void gtk_ widget _shape_combine_mask (GtkWidget *widget, GdkBitmap *shape_mask, gint 
offset_x, gint offset_y) 


Sets a shape for this widget’s GDK window. 


e void gtk _widget_input_shape_combine_mask (GtkWidget *widget, GdkBitmap *shape_mask, gint 
offset_x, gint offset_y) 


Sets an input shape for this widget’s GDK window. 


e void gtk_widget_reset_shapes (GtkWidget *widget) 


Recursively resets the shape on this widget and its descendants. 


e void gtk_widget_path (GtkWidget «widget, guint *path_length, gchar **path, gchar **path_- 
reversed) 


Obtains the full path to widget. 


e void gtk_widget_class_path (GtkWidget *widget, guint *path_length, gchar «*path, gchar x**path_- 
reversed) 


Same as gtk_widget_path(), but always uses the name of a widget's type, never uses a custom name set with 
gtk_widget_set_name(). 


e GList x gtk_widget_list_mnemonic_labels (GtkWidget *widget) 


[Deprecated] Returns a newly allocated list of the widgets, normally labels, for which this widget is a the 
target of a mnemonic (see for example, gtk_label_set_mnemonic_widget()). 


e void gtk_widget_add_mnemonic_label (GtkWidget «widget, GtkWidget label) 
[Deprecated] Adds a widget to the list of mnemonic labels for this widget. 


e void gtk_widget_remove_mnemonic_label (GtkWidget «widget, GtkWidget xlabel) 


[Deprecated] Removes a widget from the list of mnemonic labels for this widget. 


e GtkRequisition * gtk_requisition_copy (const GtkRequisition *requisition) 
Copies a GtkRequisition. 


e void gtk_requisition_free (GtkRequisition *requisition) 


Frees a GtkRequisition. 


e void gtk_widget_set_bg_transparent (GtkWidget «widget, gboolean transparent) 


Sets the widget background as transparent. 


e gboolean gtk_widget_is_bg_transparent (GtkWidget *widget) 


Returns whether the Widget is Transparent or Opaque to its parant. 
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Variables 


e guintl6 _GtkWidget::private_flags 
16 bits of internally used private flags. 


e guint8 _GtkWidget::state 


The state of the widget. 


e guint8 _GtkWidget::saved_state 


The saved state of the widget. 


e gchar x _GtkWidget::name 


The widget’s name. 


e GtkStyle * _GtkWidget::style 
The style for the widget. 


e GtkRequisition _GtkWidget::requisition 


The widget's desired size. 


e GtkAllocation _GtkWidget::allocation 


The widget's allocated size. 


e GdkWindow * _GtkWidget::window 


The widget’s window or its parent window if it does not have a window. 


e GtkWidget x _GtkWidget::parent 
The widget's parent. 


e guint _GtkWidget::bg_transparent: 1 


whether to fill the widgets background 


e void(* _GtkWidgetClass::dispatch_child_properties_changed )(Gtk Widget «widget, guint n_pspecs, 
GParamSpec *x*pspecs) 


seldomly overidden 


6.22.2 Function Documentation 
6.22.2.1 GtkRequisitionx gtk_requisition_copy (const GtkRequisition x requisition) 
Copies a GtkRequisition. 


Parameters: 


— requisition : a GtkRequisition 


Returns: 


a copy of requisition. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.22 GtkWidget 169 


6.22.2.2 void gtk_requisition_free (GtkRequisition * requisition) 
Frees a GtkRequisition. 


Parameters: 


— requisition : a GtkRequisition. 


Returns: 


void 


6.22.2.3 gboolean gtk_widget_activate (GtkWidget « widget) 


For widgets that can be "activated" (buttons, menu items, etc. 

) this function activates them. Activation is what happens when you press Enter on a widget during key 
navigation. If widget isn’t activatable, the function returns FALSE. 

Parameters: 


— widget : a GtkWidget 


Returns: 


TRUE if the widget was activatable 


6.22.2.4 void gtk_widget_add_accelerator (GtkWidget « widget, const gchar x accel_signal, 
GtkAccelGroup * accel_group, guint accel_key, GdkModifierType accel_mods, 
GtkAccelFlags accel_flags) 


Installs an accelerator for this widget in accel_group that causes accel_signal to be emitted if the accelerator 
is activated. 


The accel_group needs to be added to the widget’s toplevel via gtk_window_add_accel_group(), and the 
signal must be of type G_LRUN_ACTION. Accelerators added through this function are not user changeable 
during runtime. If you want to support accelerators that can be changed by the user, use gtk_accel_map_- 
add_entry() and gtk_widget_set_accel_path() or gtk_menu_item_set_accel_path() instead. 


Parameters: 
— widget : widget to install an accelerator on 
— accel_signal : widget signal to emit on accelerator activation 
— accel_group : accel group for this widget, added to its toplevel 
— accel_key : GDK keyval of the accelerator 
— accel_mods : modifier key combination of the accelerator 


— accel_flags : flag accelerators, e.g. GTK_ACCEL_VISIBLE 


Returns: 


void 
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6.22.2.5 void gtk_widget_add_events (GtkWidget x* widget, gint events) 


Adds the events in the bitfield events to the event mask for widget. 


See gtk_widget_set_events() for details. 


Parameters: 
— widget : a GtkWidget 


< events : an event mask, see GdkEventMask 


Returns: 


void 


6.22.2.6 void gtk_widget_add_mnemonic_label (GtkWidget « widget, GtkWidget x label) 


[Deprecated] Adds a widget to the list of mnemonic labels for this widget. 
(See gtk_widget_list_mnemonic_labels()). Note the list of mnemonic labels for the widget is cleared when 
the widget is destroyed, so the caller must make sure to update its internal state at this point as well, by 
using a connection to the destroy signal or a weak notifier. 
Parameters: 

— widget : a GtkWidget 


— label : a GtkWidget that acts as a mnemonic label for widget. 


Returns: 


void 


Deprecated 
LIMO R1 


6.22.2.7 gboolean gtk_widget_can_activate_accel (Gtk Widget « widget, guint signal_id) 
Determines whether an accelerator that activates the signal identified by signal_id can currently be acti- 
vated. 
This is done by emitting the Gtk Widget::can-activate-accel signal on widget; if the signal isn’t overridden 
by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the 
widget and all its ancestors mapped. 
Parameters: 

— widget : a GtkWidget 

— signal_id : the ID of a signal installed on widget 


Returns: 


TRUE if the accelerator can be activated. 
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6.22.2.8 gboolean gtk_widget_child_focus (GtkWidget « widget, GtkDirectionType direction) 


Causes widget to have the keyboard focus for the Gtk Window child. 


child must be a focusable widget, such as a GtkEntry; something like GtkFrame won't work. 


Parameters: 

— widget : a GtkWidget 

— directions : direction of focus movement 
Returns: 


TRUE if focus ended up inside widget 


6.22.2.9 void gtk_widget_child_notify (GtkWidget * widget, const gchar x child_property) 


Emits a "child-notify" signal for the child property child_property on widget. 


This is the analogue of g_object_notify() for child properties. 


Parameters: 
— widget : a GtkWidget 
— child_property : the name of a child property installed on the class of widget’s parent. 


Returns: 


void 


6.22.2.10  GParamSpecx gtk_widget_class_find_style_property (GtkWidgetClass x klass, const 
gchar x property_name) 


Finds a style property of a widget class by name. 


Parameters: 
— widget : a GtkWidget 


— property_name : the name of the style property to find 


Returns: 


the GParamSpec of the style property or NULL if class has no style property with that name. 


6.22.2.11 void gtk_widget_class_install_style_property (GtkWidgetClass x klass, GParamSpec x 
pspec) 


Installs a style property on a widget class. 


The parser for the style property is determined by the value type of pspec. 


Parameters: 


— widget : a GtkWidget 
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— pspec : the GParamSpec for the property 


Returns: 


void 


widget style properties 


6.22.2.12 void gtk_widget_class_install_style_property_parser (GtkWidgetClass + klass, 
GParamSpec x pspec, GtkRcPropertyParser parser) 


Installs a style property on a widget class. 


Parameters: 
— widget : a GtkWidget 
< pspec : the GParamSpec for the style property 
— parser : the parser for the style property 
Returns: 


void 


6.22.2.13 GParamSpecxx gtk_widget_class_list_style_properties (GtkWidgetClass x klass, guint « 
n_properties) 


Returns all style properties of a widget class. 


Parameters: 

— widget : a GtkWidget 

— n_properties : location to return the number of style properties found 
Returns: 


an newly allocated array of GParamSpecx. The array must be freed with g_free(). 


6.22.2.14 void gtk_widget_class_path (GtkWidget * widget, guint « path_length, gchar xx path, 
gchar xx path_reversed) 


Same as gtk_widget_path(), but always uses the name of a widget's type, never uses a custom name set 
with gtk_widget_set_name(). 
Parameters: 


— widget : a GtkWidget 
— path_length : \ocation to store the length of the class path, or NULL 
> path : location to store the class path as an allocated string, or NULL 


> path_reversed : location to store the reverse class path as an allocated string, or NULL 


Returns: 


void 
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6.22.2.15 PangoContext« gtk_widget_create_pango_context (Gtk Widget x widget) 


Creates a new PangoContext with the appropriate font map, font description, and base direction for drawing 
text for this widget. 


See also gtk_widget_get_pango_context(). 


Parameters: 


— widget : a GtkWidget 


Returns: 


the new PangoContext 


6.22.2.16 PangoLayoutx gtk_widget_create_pango_layout (GtkWidget « widget, const gchar = text) 


Creates a new PangoLayout with the appropriate font map, font description, and base direction for drawing 
text for this widget. 


If you keep a PangoLayout created in this way around, in order to notify the layout of changes to the base 
direction or font of this widget, you must call pango_layout_context_changed() in response to the style-set 
and direction-changed signals for the widget. 
Parameters: 

— widget : a GtkWidget 


— text : text to set on the layout (can be NULL) 


Returns: 


the new PangoLayout 


6.22.2.17 void gtk_widget_destroy (GtkWidget « widget) 


Destroys a widget. 


Equivalent to gtk_object_destroy(), except that you don’t have to cast the widget to GtkObject. When a 
widget is destroyed, it will break any references it holds to other objects. If the widget is inside a container, 
the widget will be removed from the container. If the widget is a toplevel (derived from GtkWindow), it 
will be removed from the list of toplevels, and the reference GTK+ holds to it will be removed. Removing 
a widget from its container or the list of toplevels results in the widget being finalized, unless you’ve added 
additional references to the widget with g object_ref() In most cases, only toplevel widgets (windows) 
require explicit destruction, because when you destroy a toplevel its children will be destroyed as well. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


174 Module Documentation 


6.22.2.18 void gtk_widget_destroyed (GtkWidget « widget, GtkWidget «« widget_pointer) 


This function sets «widget_pointer to NULL if widget_pointer != NULL. 


It’s intended to be used as a callback connected to the "destroy" signal of a widget. You connect gtk_- 
widget_destroyed() as a signal handler, and pass the address of your widget variable as user data. Then 
when the widget is destroyed, the variable will be set to NULL. Useful for example to avoid multiple copies 
of the same dialog. 
Parameters: 

— widget : a GtkWidget 


> widget_pointer : address of a variable that contains widget 


Returns: 


void 


6.22.2.19 void gtk_widget_ensure_style (GtkWidget « widget) 


Ensures that widget has a style (widget->style). 

Not a very useful function; most of the time, if you want the style, the widget is realized, and realized 
widgets are guaranteed to have a style already. 

Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.20 gboolean gtk_widget_event (GtkWidget « widget, GdkEvent « event) 
This function is used to emit the event signals on a widget (those signals should never be emitted without 
using this function to do so). 
If you want to synthesize an event though, don’t use this function; instead, use gtk_main_do_event() so 
the event will behave as if it were in the event queue. Don’t synthesize expose events; instead, use gdk_- 
window_invalidate_rect() to invalidate a region of the window. 
Parameters: 

— widget : a GtkWidget 


< event : a GdkEvent 


Returns: 


return from the event signal emission (TRUE if the event was handled) 
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6.22.2.21 void gtk_widget_freeze_child_notify (GtkWidget x widget) 


Stops emission of "child-notify" signals on widget. 


The signals are queued until gtk_widget_thaw_child_notify() is called on widget. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.22 GtkWidget« gtk_widget_get_ancestor (GtkWidget « widget, GType widget_type) 


Gets the first ancestor of widget with type widget_type. 
For example, gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the first GtkBox that’s an ancestor 


of widget. No reference will be added to the returned widget; it should not be unreferenced. See note about 
checking for a toplevel GtkWindow in the docs for gtk_widget_get_toplevel(). Note that unlike gtk_- 
widget_is_ancestor(), gtk_widget_get_ancestor() considers widget to be an ancestor of itself. 


Parameters: 


— widget : a GtkWidget 
— widget_type : ancestor type 


Returns: 


the ancestor widget, or NULL if not foun 


6.22.2.23 void gtk_widget_get_child_requisition (GtkWidget * widget, GtkRequisition « 
requisition) 


This function is only for use in widget implementations. 


Obtains widget->requisition, unless someone has forced a particular geometry on the widget (e.g. with 
gtk_widget_set_usize()), in which case it returns that geometry instead of the widget’s requisition. This 
function differs from gtk_widget_size_request() in that it retrieves the last size request value from widget- 
>requisition, while gtk_widget_size_request() actually calls the "size_request" method on widget to com- 
pute the size request and fill in widget->requisition, and only then returns widget->requisition. Because 
this function does not call the "size_request" method, it can only be used when you know that widget- 
>requisition is up-to-date, that is, gtk_widget_size_request() has been called since the last time a resize 
was queued. In general, only container implementations have this information; applications should use 
gtk_widget_size_request(). 


Parameters: 

— widget : a GtkWidget 

< requisition : a GtkRequisition to be filled in 
Returns: 


void 
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6.22.2.24 gboolean gtk_widget_get_child_visible (GtkWidget « widget) 


Gets the value set with gtk_widget_set_child_visible(). 


If you feel a need to use this function, your code probably needs reorganization. This function is only 
useful for container implementations and never should be called by an application. 


Parameters: 


— widget : a GtkWidget 


Returns: 


TRUE if the widget is mapped with the parent. 


6.22.2.25 GtkClipboard« gtk_widget_get_clipboard (GtkWidget x* widget, GdkAtom selection) 


Returns the clipboard object for the given selection to be used with widget. 


widget must have a GdkDisplay associated with it, so must be attached to a toplevel window. 


Parameters: 
— widget : a GtkWidget 
— selection : a GdkAtom which identifies the clipboard to use. GDK_SELECTION_CLIPBOARD 
gives the default clipboard. Another common value is GDK_SELECTION_PRIMARY, which 
gives the primary X selection. 
Returns: 


the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a 
clipboard object has been created, it is persistent for all time. 


6.22.2.26 GdkColormap« gtk_widget_get_colormap (GtkWidget « widget) 


Gets the colormap that will be used to render widget. 


No reference will be added to the returned colormap; it should not be unreferenced. it should not be 
unreferenced. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the colormap used by widget 


6.22.2.27 gchar» gtk_widget_get_composite_name (GtkWidget « widget) 
Obtains the composite name of a widget. 


Parameters: 


— widget : a GtkWidget 
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Returns: 


the composite name of widget, or NULL if widget is not a composite child. The string should not be 


freed when it is no longer needed. 


6.22.2.28 GdkColormap+* gtk_widget_get_default_colormap (void) 


Obtains the default colormap used to create widgets. 


Returns: 


default widget colormap 


6.22.2.29 GtkTextDirection gtk_widget_get_default_direction (void) 


Obtains the current default reading direction. 


See gtk_widget_set_default_direction(). 


Parameters: 


— widget : a GtkWidget 


Returns: 


the current default direction. 


6.22.2.30 GtkStylex gtk_widget_get_default_style (void) 


Returns the default style used by all widgets initially. 


Returns: 


the default style. This GtkStyle object is owned by GTK+ and should not be modified or freed. 


6.22.2.31 GdkVisualx gtk_widget_get_default_visual (void) 


Obtains the visual of the default colormap. 


Not really useful; used to be useful before gdk_colormap_get_visual() existed. 


Returns: 


visual of the default colormap 


6.22.2.32 GtkTextDirection gtk_widget_get_direction (GtkWidget x widget) 


Gets the reading direction for a particular widget. 


See gtk_widget_set_direction(). 
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Parameters: 


— widget : a GtkWidget 


Returns: 


the reading direction for the widget. 


6.22.2.33 GdkDisplay« gtk_widget_get_display (GtkWidget « widget) 


Get the GdkDisplay for the toplevel window associated with this widget. 


This function can only be called after the widget has been added to a widget hierarchy with a GtkWindow 
at the top. In general, you should only create display specific resources when a widget has been realized, 
and you should free those resources when the widget is unrealized. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.34 gint gtk_widget_get_events (GtkWidget « widget) 


Returns the event mask for the widget (a bitfield containing flags from the GdkEventMask enumeration). 


These are the events that the widget will receive. These are the events that the widget will receive. 


Parameters: 


— widget : a GtkWidget 


Returns: 


event mask for widget 


6.22.2.35 GdkExtensionMode gtk_widget_get_extension_events (GtkWidget « widget) 


Retrieves the extension events the widget will receive;. 


Parameters: 


— widget : a GtkWidget 


Returns: 


extension events for widget 
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6.22.2.36 GtkRcStylex gtk_widget_get_modifier_style (GtkWidget « widget) 


Returns the current modifier style for the widget. 


(As set by gtk_widget_modify_style().) If no style has previously set, a new GtkRcStyle will be created 
with all values unset, and set as the modifier style for the widget. If you make changes to this rc style, you 
must call gtk_widget_modify_style(), passing in the returned rc style, to make sure that your changes take 
effect. Caution: passing the style back to gtk_widget_modify_style() will normally end up destroying it, 
because gtk_widget_modify_style() copies the passed-in style and sets the copy as the new modifier style, 
thus dropping any reference to the old modifier style. Add a reference to the modifier style if you want to 
keep it alive. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the modifier style for the widget. This rc style is owned by the widget. If you want to keep a pointer 
to value this around, you must add a refcount using g_object_ref(). 


6.22.2.37 G_CONST_RETURN gchar» gtk_widget_get_name (Gtk Widget « widget) 


Retrieves the name of a widget. 


See gtk_widget_set_name() for the significance of widget names. 


Parameters: 


— widget : a GtkWidget 


Returns: 


name of the widget. This string is owned by GTK+ and should not be modified or freed 


6.22.2.38 gboolean gtk_widget_get_no_show_all (GtkWidget x widget) 


Returns the current value of the "no_show_all" property, which determines whether calls to gtk_widget_- 
show_all() and gtk_widget_hide_all() will affect this widget. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the current value of the "no_show_all" property. 


6.22.2.39 PangoContextx gtk_widget_get_pango_context (GtkWidget « widget) 


Gets a PangoContext with the appropriate font map, font description, and base direction for this widget. 


Unlike the context returned by gtk_widget_create_pango_context(), this context is owned by the widget (it 
can be used until the screen for the widget changes or the widget is removed from its toplevel), and will 
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be updated to match any changes to the widget's attributes. If you create and keep a PangoLayout using 
this context, you must deal with changes to the context by calling pango_layout_context_changed() on the 
layout in response to the style-set and direction-changed signals for the widget. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the PangoContext for the widget. 


6.22.2.40 GtkWidget« gtk_widget_get_parent (GtkWidget « widget) 
Returns the parent container of widget. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the parent container of widget, or NULL 


6.22.2.41 GdkWindow« gtk_widget_get_parent_window (GtkWidget « widget) 


Gets widget’s parent window. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the parent window of widget.s 


6.22.2.42 void gtk_widget_get_pointer (GtkWidget x widget, gint « x, gint x y) 


Obtains the location of the mouse pointer in widget coordinates. 


Widget coordinates are a bit odd; for historical reasons, they are defined as widget->window coordinates 
for widgets that are not GTK_NO_WINDOW widgets, and are relative to widget->allocation.x, widget- 
>allocation.y for widgets that are GTK_NO_WINDOW widgets. 


Parameters: 


— widget : a GtkWidget 
— x : return location for the X coordinate, or NULL 


— y : return location for the Y coordinate, or NULL 


Returns: 


void 
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6.22.2.43 GdkWindow« gtk_widget_get_root_window (GtkWidget « widget) 


Get the GdkDisplay for the toplevel window associated with this widget. 


This function can only be called after the widget has been added to a widget hierarchy with a GtkWindow 
at the top. The root window is useful for such purposes as creating a popup Gdk Window associated with 
the window. In general, you should only create display specific resources when a widget has been realized, 
and you should free those resources when the widget is unrealized. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the GdkDisplay for the toplevel for this widget. 


6.22.2.44 GdkScreen« gtk_widget_get_screen (Gtk Widget « widget) 


Get the GdkScreen from the toplevel window associated with this widget. 


This function can only be called after the widget has been added to a widget hierarchy with a Gtk Window 
at the top. In general, you should only create screen specific resources when a widget has been realized, 
and you should free those resources when the widget is unrealized. 


Parameters: 
— widget : a GtkWidget 


Returns: 


the GdkScreen for the toplevel for this widget. 


6.22.2.45 GtkSettings« gtk_widget_get_settings (GtkWidget « widget) 


Gets the settings object holding the settings (global property settings, RC file information, etc) used for this 
widget. 


Note that this function can only be called when the GtkWidget is attached to a toplevel, since the settings 
object is specific to a particular GdkScreen. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the relevant GtkSettings object 


6.22.2.46 void gtk_widget_get_size_request (GtkWidget * widget, gint x width, gint x height) 


Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request(). 


A value of -1 stored in width or height indicates that that dimension has not been set explicitly and the 
natural requisition of the widget will be used intead. See gtk_widget_set_size_request(). To get the size a 
widget will actually use, call gtk_widget_size_request() instead of this function. 
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Parameters: 
— widget : a GtkWidget 
— width : return location for width, or NULL 


— height : return location for height, or NULL 


Returns: 


void 


6.22.2.47 GtkStylex gtk_widget_get_style (GtkWidget « widget) 


Simply an accessor function that returns widget->style. 


Parameters: 


— widget : a GtkWidget 


Returns: 


the widget’s GtkStyle 


6.22.2.48 GtkWidget« gtk_widget_get_toplevel (GtkWidget « widget) 


This function returns the topmost widget in the container hierarchy widget is a part of. 


If widget has no parent widgets, it will be returned as the topmost widget. No reference will be added 
to the returned widget; it should not be unreferenced. Note the difference in behavior vs. gtk_widget_- 
get_ancestor(); gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW) would return NULL if widget 
wasn’t inside a toplevel window, and if the window was inside a GtkWindow-derived widget which was 
in turn inside the toplevel GtkWindow. While the second case may seem unlikely, it actually happens 
when a GtkPlug is embedded inside a GtkSocket within the same application. To reliably find the toplevel 
GtkWindow, use gtk_widget_get_toplevel() and check if the TOPLEVEL flags is set on the result. 


GtkWidget *toplevel = gtk_widget_get_toplevel (widget); 
if (GTK_WIDGET_TOPLEVEL (toplevel)) 
{ 

[ Perform action on toplevel. ] 


} 


Parameters: 


— widget : a GtkWidget 


Returns: 


the topmost ancestor of widget, or widget itself if there’s no ancestor. 


6.22.2.49 GdkVisualx gtk_widget_get_visual (Gtk Widget « widget) 


Gets the visual that will be used to render widget. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.22 GtkWidget 183 


Parameters: 


— widget : a GtkWidget 


Returns: 


the visual for widgets 


6.22.2.50 void gtk_widget_grab_default (GtkWidget « widget) 


Causes widget to become the default widget. 


widget must have the GTK_CAN_DEFAULT flag set; typically you have to set this flag yourself by calling 
GTK_WIDGET_SET_FLAGS (widget, GTK_CAN_DEFAULT). The default widget is activated when the 
user presses Enter in a window. Default widgets must be activatable, that is, gtk_widget_activate() should 
affect them. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.51 void gtk_widget_grab_focus (GtkWidget « widget) 


Causes widget to have the keyboard focus for the Gtk Window it’s inside. 

widget must be a focusable widget, such as a GtkEntry; something like GtkFrame won't work. (More 
precisely, it must have the GTK_CAN_FOCUS flag set.) 

Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.52 gboolean gtk_widget_has_screen (GtkWidget « widget) 


Checks whether there is a GdkScreen is associated with this widget. 

All toplevel widgets have an associated screen, and all widgets added into a heirarchy with a toplevel 
window at the top. 

Parameters: 


— widget : a GtkWidget 


Returns: 


TRUE if there is a GdkScreen associcated with the widget. 
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6.22.2.53 void gtk_widget_hide (GtkWidget « widget) 
Reverses the effects of gtk_widget_show(), causing the widget to be hidden (invisible to the user). 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.54 void gtk_widget_hide_all (GtkWidget « widget) 
Recursively hides a widget and any child widgets. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.55 gboolean gtk_widget_hide_on_delete (GtkWidget x widget) 


Utility function; intended to be connected to the "delete_event" signal on a Gtk Window. 


The function calls gtk_widget_hide() on its argument, then returns TRUE. If connected to "delete_event", 
the result is that clicking the close button for a window (on the window frame, top right corner usually) will 
hide but not destroy the window. By default, GTK+ destroys windows when "delete_event" is received. 


Parameters: 


— widget : a GtkWidget 


Returns: 


TRUE 


6.22.2.56 void gtk_widget_input_shape_combine_mask (GtkWidget x widget, GdkBitmap * 
shape_mask, gint offset_x, gint offset_y) 


Sets an input shape for this widget’s GDK window. 
This allows for windows which react to mouse click in a nonrectangular region, see gdk_window_input_- 
shape_combine_mask() for more information. 
Parameters: 
— widget : a GtkWidget 
— shape_mask : shape to be added, or NULL to remove an existing shape. 


—offset_x : X position of shape mask with respect to window. 
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—offset_y : Y position of shape mask with respect to window. 


Returns: 


void 


6.22.2.57 gboolean gtk_widget_intersect (GtkWidget x* widget, GdkRectangle « area, 
GdkRectangle intersection) 


Computes the intersection of a widget’s area and area, storing the intersection in intersection, and returns 
TRUE if there was an intersection. 


intersection may be NULL if you’re only interested in whether there was an intersection. 


Parameters: 
— widget : a GtkWidget 
— area : arectangle 


— intersection : rectangle to store intersection of widget and area 


Returns: 


TRUE if there was an intersection 


6.22.2.58 gboolean gtk_widget_is_ancestor (GtkWidget « widget, GtkWidget x ancestor) 
Determines whether widget is somewhere inside ancestor, possibly with intermediate containers. 


Parameters: 


— widget : a GtkWidget 
< ancestor : another GtkWidget 


Returns: 


TRUE if ancestor contains widget as a child, grandchild, great grandchild, etc. 


6.22.2.59 gboolean gtk_widget_is_bg_transparent (Gtk Widget « widget) 
Returns whether the Widget is Transparent or Opaque to its parant. 


Parameters: 


widget [in] a GtkWidget 


Returns: 
Transparent or Not.] TRUE means, widget will be rendered transparently on its Parant. FALSE means 
Widget is Opaque, and its exposed area of parant will be cleard out by the widget. 

Since 


LIMO RI 
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6.22.2.60 gboolean gtk_widget_is_composited (GtkWidget « widget) 
Whether widget can rely on having its alpha channel drawn correctly. 
On X11 this function returns whether a compositing manager is running for widget's screen 


Parameters: 


— widget : a GtkWidget 


Returns: 


TRUE if the widget can rely on its alpha channel being drawn correctly. 


Compositing manager functionality 


6.22.2.61 gboolean gtk_widget_is_focus (GtkWidget « widget) 


Determines if the widget is the focus widget within its toplevel. 


(This does not mean that the HAS_FOCUS flag is necessarily set; HAS_FOCUS will only be set if the 
toplevel widget additionally has the global input focus.) 


Parameters: 


— widget : a GtkWidget 


Returns: 


TRUE if the widget is the focus widget. 


6.22.2.62  GListx gtk_widget_list_accel_closures (GtkWidget x widget) 


Lists the closures used by widget for accelerator group connections with gtk_accel_group_connect_by_- 
path() or gtk_accel_group_connect(). 


The closures can be used to monitor accelerator changes on widget, by connecting to the accel_changed 
signal of the GtkAccelGroup of a closure which can be found out with gtk_accel_group_from_accel_- 
closure(). 


Parameters: 


— widget : a GtkWidget 


Returns: 


a newly allocated GList of closures 


6.22.2.63 GList« gtk_widget_list_mnemonic_labels (GtkWidget « widget) 


[Deprecated] Returns a newly allocated list of the widgets, normally labels, for which this widget is a the 
target of a mnemonic (see for example, gtk_label_set_mnemonic_widget()). 


The widgets in the list are not individually referenced. If you want to iterate through the list and perform 
actions involving callbacks that might destroy the widgets, you must call g_list_foreach (result, (GFunc)g_- 
object_ref, NULL) first, and then unref all the widgets afterwards. 
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Parameters: 


— widget : a GtkWidget 
Returns: 


the list of mnemonic labels; free this list with g_list_free() when you are done with it. 


Deprecated 
LIMO RI 


6.22.2.64 void gtk_widget_map (GtkWidget « widget) 
This function is only for use in widget implementations. 
Causes a widget to be mapped if it isn’t already. 
Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.65 gboolean gtk_widget_mnemonic_activate (GtkWidget « widget, gboolean group_cycling) 
[Deprecated] Activates the widget mnemonic 


Parameters: 

— widget : a GtkWidget 

— group_cycling : the ID of a signal installed on widget 
Returns: 

TRUE if the mnemonic can be activated. 
Deprecated 

LIMO RI 


6.22.2.66 void gtk_widget_modify_base (GtkWidget x* widget, GtkStateType state, const GdkColor 
x color) 


Sets the base color for a widget in a particular state. 


All other style values are left untouched. The base color is the background color used along with the 
text color (see gtk_widget_modify_text()) for widgets such as GtkEntry and GtkTextView. See also gtk_- 
widget_modify_style(). Note that "no window" widgets (which have the GTK_NO_WINDOW flag set) 
draw on their parent containers window and thus may not draw any background themselves. This is the 
case for e.g. GtkLabel. To modify the background of such widgets, you have to set the base color on their 
parent; if you want to set the background of a rectangular area around a label, try placing the label in a 
GtkEventBox widget and setting the base color on that. 
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Parameters: 
— widget : a GtkWidget 
< state : the state for which to set the base color. 


— color : the color to assign (does not need to be allocated), or NULL to undo the effect of previous 
calls to of gtk_widget_modify_base(). 


Returns: 


void 


6.22.2.67 void gtk_widget_modify_bg (GtkWidget x widget, GtkStateType state, const GdkColor + 
color) 


Sets the background color for a widget in a particular state. 


All other style values are left untouched. See also gtk_widget_modify_style(). Note that "no window" 
widgets (which have the GTK_NO_WINDOW flag set) draw on their parent container's window and thus 
may not draw any background themselves. This is the case for e.g. GtkLabel. To modify the background 
of such widgets, you have to set the background color on their parent; 1f you want to set the background of 
a rectangular area around a label, try placing the label in a GtkEventBox widget and setting the background 
color on that 


Parameters: 
— widget : a GtkWidget 


— state : the state for which to set the background color. 


— color : the color to assign (does not need to be allocated), or NULL to undo the effect of previous 
calls to of gtk_widget_modify_bg(). 


Returns: 


void 


6.22.2.68 void gtk_widget_modify_fg (GtkWidget « widget, GtkStateType state, const GdkColor x 
color) 


Sets the foreground color for a widget in a particular state. 


All other style values are left untouched. See also gtk_widget_modify_style(). 


Parameters: 
— widget : a GtkWidget 
— state : the state for which to set the foreground color. 


— color : the color to assign(does not need to be allocated), or NULL to undo the effect of previous 
calls to of gtk_widget_modify_fg(). 


Returns: 


void 
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6.22.2.69 void gtk_widget_modify_font (GtkWidget « widget, PangoFontDescription * font_desc) 


Sets the font to use for a widget. 


All other style values are left untouched. See also gtk_widget_modify_style(). 


Parameters: 
— widget : a GtkWidget 
— font_desc : the font description to use, or NULL to undo the effect of previous calls to gtk_- 
widget_modify_font(). 
Returns: 


void 


6.22.2.70 void gtk_widget_modify_style (GtkWidget « widget, GtkRcStyle « style) 


Modifies style values on the widget. 


Modifications made using this technique take precedence over style values set via an RC file, however, they 
will be overriden if a style is explicitely set on the widget using gtk_widget_set_style(). The GtkRcStyle 
structure is designed so each field can either be set or unset, so it is possible, using this function, to modify 
some style values and leave the others unchanged. Note that modifications made with this function are 
not cumulative with previous calls to gtk_widget_modify_style() or with such functions as gtk_widget_- 
modify_fg(). If you wish to retain previous values, you must first call gtk_widget_get_modifier_style(), 
make your modifications to the returned style, then call gtk_widget_modify_style() with that style. On the 
other hand, if you first call gtk_widget_modify_styleQ, subsequent calls to such functions gtk_widget_- 
modify_fg() will have a cumulative effect with the initial modifications. 


Parameters: 
— widget : a GtkWidget 
— style : the GtkRcStyle holding the style modifications 


Returns: 


void 


6.22.2.71 void gtk_widget_modify_text (GtkWidget « widget, GtkStateType state, const GdkColor 
x color) 


Sets the text color for a widget in a particular state. 


All other style values are left untouched. The text color is the foreground color used along with the base 
color (see gtk_widget_modify_base()) for widgets such as GtkEntry and GtkTextView. See also gtk - 
widget_modify_style(). 


Parameters: 
— widget : a GtkWidget 
< state : the state for which to set the text color. 


— color : the color to assign (does not need to be allocated), or NULL to undo the effect of previous 
calls to of gtk_widget_modify_text(). 
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Returns: 


void 


6.22.2.72 GtkWidget« gtk_widget_new (GType type, const gchar « first_property_name, ...) 


This is a convenience function for creating a widget and setting its properties in one go. 


For example you might write: gtk_widget_new (GTK_TYPE_LABEL, "label", "Hello World", "xalign", 
0.0, NULL) to create a left-aligned label. Equivalent to g_object_new(), but returns a widget so you don’t 
have to cast the object yourself. 


Parameters: 


< type : type ID of the widget to creates 
— first_property_name : name of first property to set 


— ... : value of first property, followed by more properties, NULL-terminated 


Returns: 


a new GtkWidget of type widget_type 


6.22.2.73 void gtk_widget_path (GtkWidget « widget, guint x path_length, gchar xx path, gchar xx 
path_reversed) 
Obtains the full path to widget. 


The path is simply the name of a widget and all its parents in the container hierarchy, separated by periods. 
The name of a widget comes from gtk_widget_get_name(). Paths are used to apply styles to a widget in 
gtkrc configuration files. Widget names are the type of the widget by default (e.g. "GtkButton") or can 
be set to an application-specific value with gtk_widget_set_name(). By setting the name of a widget, you 
allow users or theme authors to apply styles to that specific widget in their gtkrc file. path_reversed_p 
fills in the path in reverse order, That is starting with widget's name instead of starting with the name of 
widget's outermost ancestor. 

Parameters: 


— widget : a GtkWidget 
> path_length : location to store length of the path, or NULL 
> path : location to store allocated path string, or NULL 


> path_reversed : location to store allocated reverse path string, or NULL 


Returns: 


void 


6.22.2.74 void gtk_widget_pop_colormap (void) 
Removes a colormap pushed with gtk_widget_push_colormap(). 


Returns: 


void 
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6.22.2.75 void gtk_widget_pop_composite_child (void) 


Cancels the effect of a previous call to gtk_widget_push_composite_child(). 


Returns: 


void 


6.22.2.76 void gtk_widget_push_colormap (GdkColormap * cmap) 

Pushes cmap onto a global stack of colormaps; the topmost colormap on the stack will be used to create all 
widgets. 

Remove cmap with gtk_widget_pop_colormap(). There's little reason to use this function. 

Parameters: 


< cmap : a GdkColormap 


Returns: 


void 


6.22.2.77 void gtk_widget_push_composite_child (void) 


Makes all newly-created widgets as composite children until the corresponding gtk _widget_pop_- 
composite_child() call. 


A composite child is a child that’s an implementation detail of the container it’s inside and should not 
be visible to people using the container. Composite children aren’t treated differently by GTK (but see 
gtk_container_foreach() vs. gtk_container_forall()), but e.g. GUI builders might want to treat them in a 
different way. 


Here is a simple example: 


gtk_widget_push_composite_child (); 
scrolled_window->hscrollbar = gtk_hscrollbar_new (hadjustment) ; 
gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar") ; 
gtk_widget_pop_composite_child (); 
gtk_widget_set_parent (scrolled_window->hscrollbar, 

GTK_WIDGET (scrolled_window) ); 
g_object_ref (scrolled_window->hscrollbar) ; 


Returns: 


void 


6.22.2.78 void gtk_widget_queue_draw (GtkWidget « widget) 


Equivalent to calling gtk_widget_queue_draw_area() for the entire area of a widget. 


Parameters: 
— widget : a GtkWidget 
Returns: 


void 
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6.22.2.79 void gtk_widget_queue_draw_area (GtkWidget x widget, gint x, gint y, gint width, gint 
height) 


Invalidates the rectangular area of widget defined by x, y, width and height by calling gdk_window_- 
invalidate_rect() on the widget’s window and all its child windows. 


Once the main loop becomes idle (after the current batch of events has been processed, roughly), the win- 
dow will receive expose events for the union of all regions that have been invalidated. Normally you would 
only use this function in widget implementations. You might also use it, or gdk_window_invalidate_rect() 
directly, to schedule a redraw of a GtkDrawingArea or some portion thereof. Frequently you can just call 
gdk_window_invalidate_rect() or gdk_window_invalidate_region() instead of this function. Those func- 
tions will invalidate only a single window, instead of the widget and all its children. The advantage of 
adding to the invalidated region compared to simply drawing immediately is efficiency; using an invalid 
region ensures that you only have to redraw one time. 


Parameters: 
— x : x coordinate of upper-left corner of rectangle to redraw 
— y : y coordinate of upper-left corner of rectangle to redraw 
— width : width of region to draw 
— height : height of region to draw 

Returns: 


void 


6.22.2.80 void gtk_widget_queue_resize (GtkWidget « widget) 


This function is only for use in widget implementations. 


Flags a widget to have its size renegotiated; should be called when a widget for some reason has a new size 
request. For example, when you change the text in a GtkLabel, GtkLabel queues a resize to ensure there's 
enough space for the new text. 


Parameters: 
— widget : a GtkWidget 


Returns: 


void 


6.22.2.81 void gtk_widget_queue_resize_no_redraw (GtkWidget x widget) 


Flags a widget to have its size renegotiated; should be called when a widget for some reason has a new size 
request. 
This function works like gtk_widget_queue_resize(), except that the widget is not invalidated. 
Parameters: 

— widget : a GtkWidget 
Returns: 


void 
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6.22.2.82 void gtk_widget_realize (GtkWidget * widget) 


Creates the GDK (windowing system) resources associated with a widget. 


For example, widget->window will be created when a widget is realized. Normally realization happens 
implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped 
automatically. Realizing a widget requires all the widget's parent widgets to be realized; calling gtk_- 
widget_realize() realizes the widget's parents in addition to widget itself. If a widget is not yet inside a 
toplevel window when you realize it, bad things will happen. This function is primarily used in widget 
implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better 
approach is to connect to a signal that will be called after the widget is realized automatically, such as 
"expose_event". Or simply g_signal_connect_after() to the "realize" signal. 

Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.83 GtkWidget« gtk_widget_ref (GtkWidget « widget) 


Adds a reference to a widget. 

This function is exactly the same as calling g_object_ref(), and exists mostly for historical reasons. It can 
still be convenient to avoid casting a widget to a GObject, it saves a small amount of typing. 

Parameters: 


— widget : a GtkWidget 


Returns: 


the widget that was referenced 


6.22.2.84 GdkRegionx gtk_widget_region_intersect (GtkWidget x* widget, GdkRegion x region) 


Computes the intersection of a widget’s area and region, returning the intersection. 


The result may be empty, use gdk_region_empty() to check. 


Parameters: 
— widget : a GtkWidget 


— region : a GdkRegion, in the same coordinate system as widget->allocation. That is, relative to 
widget->window for NO_WINDOW widgets; relative to the parent window of widget->window 
for widgets with their own window. 


Returns: 


A newly allocated region holding the intersection of widget and region. The coordinates of the return 
value are relative to widget->window for NO_WINDOW widgets, and relative to the parent window 
of widget->window for widgets with their own window. 
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6.22.2.85 gboolean gtk_widget_remove_accelerator (GtkWidget « widget, GtkAccelGroup + 
accel_group, guint accel_key, GdkModifierType accel_mods) 


Removes an accelerator from widget, previously installed with gtk_widget_add_accelerator(). 


Parameters: 
— widget : a GtkWidget 
— accel_group : accel group for this widget 
— accel_key : GDK keyval of the accelerator 


— accel_mods : modifier key combination of the accelerator 


Returns: 


whether an accelerator was installed and could be removed 


6.22.2.86 void gtk_widget_remove_mnemonic_label (GtkWidget « widget, GtkWidget « label) 


[Deprecated] Removes a widget from the list of mnemonic labels for this widget. 


The widget must have previously been added to the list with gtk_widget_add_mnemonic_label(). 


Parameters: 
— widget : a GtkWidget 


— label : a GtkWidget that was previously set as a mnemnic label for widget with gtk_widget_add_- 
mnemonic_label(). 


Returns: 


void 


Deprecated 
LIMO R1 


6.22.2.87 GdkPixbuf* gtk_widget_render_icon (GtkWidget « widget, const gchar x stock_id, 
GtkIconSize size, const gchar x detail) 


A convenience function that uses the theme engine and RC file settings for widget to look up stock_id and 
render it to a pixbuf. 


stock_id should be a stock icon ID such as GTK_STOCK_OPEN or GTK_STOCK_OK. size should be a 
size such as GTK_ICON_SIZE_MENU. detail should be a string that identifies the widget or code doing 
the rendering, so that theme engines can special-case rendering for that widget or code. The pixels in the 
returned GdkPixbuf are shared with the rest of the application and should not be modified. The pixbuf 
should be freed after use with g_object_unref(). 


Parameters: 
— widget : a GtkWidget 
<+ stock_id : a stock ID 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.22 GtkWidget 195 


— size : astock size. A size of (GtkIconSize)-1 means render at the size of the source and don’t scale 
(1f there are multiple source sizes, GTK+ picks one of the available sizes). 


— detail : render detail to pass to theme engine 


Returns: 


a new pixbuf, or NULL if the stock ID wasn’t known 


6.22.2.88 void gtk_widget_reparent (GtkWidget x widget, GtkWidget x new_parent) 


Moves a widget from one GtkContainer to another, handling reference count issues to avoid destroying the 
widget. 


Parameters: 
— widget : a GtkWidget 


— new_parent : a GtkContainer to move the widget into 


Returns: 


void 


6.22.2.89 void gtk_widget_reset_rc_styles (GtkWidget « widget) 


Reset the styles of widget and all descendents, so when they are looked up again, they get the correct values 
for the currently loaded RC file settings. 


This function is not useful for applications. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.90 void gtk_widget_reset_shapes (GtkWidget « widget) 


Recursively resets the shape on this widget and its descendants. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


internal function 
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6.22.2.91 gint gtk_widget_send_expose (Gtk Widget « widget, GdkEvent x event) 


Very rarely-used function. 


This function is used to emit an expose event signals on a widget. This function is not normally used 
directly. The only time it is used is when propagating an expose event to a child NO_WINDOW widget, 
and that is normally done using gtk_container_propagate_expose(). If you want to force an area of a 
window to be redrawn, use gdk_window_invalidate_rect() or gdk_window_invalidate_region(). To cause 
the redraw to be done immediately, follow that call with a call to gdk_window_process_updates(). 


Parameters: 
— widget : a GtkWidget 


< event : a GdkEvent 


Returns: 


return from the event signal emission (TRUE if the event was handled) 


6.22.2.92 void gtk widget_set_accel_path (GtkWidget « widget, const gchar x accel_path, 
GtkAccelGroup * accel_group) 


Given an accelerator group, accel_group, and an accelerator path, accel_path, sets up an accelerator in 
accel_group so whenever the key binding that is defined for accel_path is pressed, widget will be activated. 


This removes any accelerators (for any accelerator group) installed by previous calls to gtk_widget_set_- 
accel_path(). Associating accelerators with paths allows them to be modified by the user and the mod- 
ifications to be saved for future use. (See gtk_accel_map_save().) This function is a low level function 
that would most likely be used by a menu creation system like GtkItemFactory. If you use GtkItemFactory, 
setting up accelerator paths will be done automatically. Even when you you aren't using GtkItemFactory, if 
you only want to set up accelerators on menu items gtk_menu_item_set_accel_path() provides a somewhat 
more convenient interface. 


Parameters: 
— widget : a GtkWidget 
— accel_path : path used to look up the accelerator 


— accel_group : a GtkAccelGroup. 


Returns: 


void 


6.22.2.93 void gtk_widget_set_app_paintable (GtkWidget « widget, gboolean app_paintable) 


Sets whether the application intends to draw on the widget in an expose-event handler. 


This is a hint to the widget and does not affect the behavior of the GTK+ core; many widgets ignore this 
flag entirely. For widgets that do pay attention to the flag, such as GtkEventBox and GtkWindow, the effect 
is to suppress default themed drawing of the widget’s background. (Children of the widget will still be 
drawn.) The application is then entirely responsible for drawing the widget background. Note that the 
background is still drawn when the widget is mapped. If this is not suitable (e.g. because you want to make 
a transparent window using an RGBA visual), you can work around this by doing: 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.22 GtkWidget 197 


gtk_widget_realize (window); 
gdk_window_set_back_pixmap (window->window, NULL, FALSE); 
gtk_widget_show (window) ; 


Parameters: 

— widget : a GtkWidget 

— app_paintable : TRUE if the application will paint on the widget 
Returns: 


void 


6.22.2.94 void gtk_widget_set_bg_transparent (GtkWidget * widget, gboolean transparent) 


Sets the widget background as transparent. 


This widget will not clearout its parents data. Widget will be drawn on top its Parent without clearing the 
Parent rendering data. 


Parameters: 


widget [in] a GtkWidget 
transparent [in] TRUE means, widget will be rendered transparently on its Parant. FALSE means 
Widget is Opaque, and its exposed area of parant will be cleard out by the widget. 


Returns: 
void 
Since 


LIMO R1 


6.22.2.95 void gtk_widget_set_child_visible (GtkWidget « widget, gboolean is_visible) 


Sets whether widget should be mapped along with its when its parent is mapped and widget has been shown 
with gtk_widget_show(). 
Parameters: 
— widget : a GtkWidget 
<— is_visible : if TRUE, widget should be mapped along with its parent. 
Returns: 


void 


6.22.2.96 void gtk_widget_set_colormap (GtkWidget x widget, GdkColormap « colormap) 


The following functions must not be called on an already realized widget. 


Because it is possible that somebody can call get_colormap() or get_visual() and save the result, these 
functions are probably only safe to call in a widget’s init() function. 


Sets the colormap for the widget to the given value. Widget must not have been previously realized. This 
probably should only be used from an init() function (i.e. from the constructor for the widget). 
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Parameters: 
— widget : a GtkWidget 


— colormap : a colormap 


Returns: 


void 


6.22.2.97 void gtk_widget_set_composite_name (GtkWidget x widget, const gchar x name) 


Sets a widgets composite name. 


The widget must be a composite child of its parent; see gtk_widget_push_composite_child(). 


Parameters: 
— widget : a GtkWidget 


< name : the name to set. 


Returns: 


void 


Handle composite names for GTK_COMPOSITE_CHILD widgets, the returned name is newly allocated 


6.22.2.98 void gtk_widget_set_default_colormap (GdkColormap = colormap) 


Sets the default colormap to use when creating widgets. 


gtk_widget_push_colormap() is a better function to use if you only want to affect a few widgets, rather 
than all widgets. 


Parameters: 


— colormap : a GdkColormap 


Returns: 


void 


6.22.2.99 void gtk_widget_set_default_direction (GtkTextDirection dir) 


Sets the default reading direction for widgets where the direction has not been explicitly set by gtk_- 
widget_set_direction(). 


Parameters: 


— dir : the new default direction. This cannot be GTK_TEXT_DIR_NONE. 


Returns: 


void 
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6.22.2.100 void gtk_widget_set_direction (GtkWidget « widget, GtkTextDirection dir) 


Sets the reading direction on a particular widget. 


This direction controls the primary direction for widgets containing text, and also the direction in which 
the children of a container are packed. The ability to set the direction is present in order so that correct 
localization into languages with right-to-left reading directions can be done. Generally, applications will 
let the default reading direction present, except for containers where the containers are arranged in an order 
that is explicitely visual rather than logical (such as buttons for text justification). If the direction is set to 
GTK_TEXT_DIR_NONE, then the value set by gtk_widget_set_default_direction() will be used. 


Parameters: 


— widget : a GtkWidget 


— dir : the new direction 


Returns: 


void 


Functions for setting directionality for widgets 


6.22.2.101 void gtk_widget_set_double_buffered (GtkWidget « widget, gboolean double_buffered) 
Widgets are double buffered by default; you can use this function to turn off the buffering. 


Parameters: 
— widget : a GtkWidget 
— double_buffered : TRUE to double-buffer a widget 


Returns: 


void 


6.22.2.102 void gtk_widget_set_events (GtkWidget x* widget, gint events) 


Sets the event mask (see GdkEventMask) for a widget. 


The event mask determines which events a widget will receive. Keep in mind that different widgets have 
different default event masks, and by changing the event mask you may disrupt a widget’s functionality, so 
be careful. This function must be called while a widget is unrealized. Consider gtk_widget_add_events() 
for widgets that are already realized, or if you want to preserve the existing event mask. This function 
can’t be used with GTK_NO_WINDOW widgets; to get events on those widgets, place them inside a 
GtkEventBox and receive events on the event box. 

Parameters: 

— widget : a GtkWidget 


< events : event mask 


Returns: 


void 
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6.22.2.103 void gtk_widget_set_extension_events (GtkWidget « widget, GdkExtensionMode mode) 


Sets the extension events mask to mode. 


See GdkExtensionMode and gdk_input_set_extension_events(). 


Parameters: 

— widget : a GtkWidget 

< mode : bitfield of extension events to receive 
Returns: 


void 


6.22.2.104 void gtk_widget_set_name (GtkWidget * widget, const gchar x name) 


Widgets can be named, which allows you to refer to them from a gtkrc file. 


You can apply a style to widgets with a particular name in the gtkrc file. See the documentation for gtkrc 
files (on the same page as the docs for GtkRcStyle). Note that widget names are separated by periods in 
paths (see gtk_widget_path()), so names with embedded periods may cause confusion. 


Parameters: 


— widget : a GtkWidget 


< name : name for the widget 


Returns: 


void 


6.22.2.105 void gtk_widget_set_no_show_all (GtkWidget * widget, gboolean no_show_all) 


Sets the "no_show_all" property, which determines whether calls to gtk_widget_show_all() and gtk_- 
widget_hide_all() will affect this widget. 


This is mostly for use in constructing widget hierarchies with externally controlled visibility, see 
GtkUlManager. 


Parameters: 

— widget : a GtkWidget 

— no_show_all : the new value for the "no_show_all" property 
Returns: 


void 


6.22.2.106 void gtk_widget_set_parent (GtkWidget x* widget, GtkWidget * parent) 


This function is useful only when implementing subclasses of GtkContainer. 


Sets the container as the parent of widget, and takes care of some details such as updating the state and 
style of the child to reflect its new location. 
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Parameters: 
— widget : a GtkWidget 


— parent : parent container 


Returns: 


void 


6.22.2.107 void gtk_widget_set_parent_window (GtkWidget « widget, GdkWindow + 
parent_window) 


Sets a non default parent window for widget. 


Parameters: 
— widget : a GtkWidget 


— parent_window : the new parent window. 


Returns: 


void 


6.22.2.108 void gtk_widget_set_redraw_on_allocate (GtkWidget x* widget, gboolean 
redraw_on_allocate) 


Sets whether the entire widget is queued for drawing when its size allocation changes. 
By default, this setting is TRUE and the entire widget is redrawn on every size change. If your widget 
leaves the upper left unchanged when made bigger, turning this setting on will improve performance. 
Parameters: 

— widget : a GtkWidget 


— redraw_on_allocate : if TRUE, the entire widget will be redrawn when it is allocated to a new 
size. Otherwise, only the new portion of the widget will be redrawn. 


Returns: 


void 


6.22.2.109 gboolean gtk_widget_set_scroll_adjustments (GtkWidget « widget, GtkAdjustment « 
hadjustment, GtkAdjustment x vadjustment) 


For widgets that support scrolling, sets the scroll adjustments and returns TRUE. 

For widgets that don't support scrolling, does nothing and returns FALSE. Widgets that don't support 
scrolling can be scrolled by placing them in a GtkViewport, which does support scrolling. 

Parameters: 


— widget : a GtkWidget 
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— hadjustment : an adjustment for horizontal scrolling, or NULL 


— vadjustment : an adjustment for vertical scrolling, or NULL 


Returns: 


TRUE if the widget supports scrolling 


6.22.2.110 void gtk_widget_set_sensitive (GtkWidget « widget, gboolean sensitive) 


Sets the sensitivity of a widget. 


A widget is sensitive if the user can interact with it. Insensitive widgets are "grayed out" and the user can't 
interact with them. Insensitive widgets are known as "inactive", "disabled", or "ghosted" in some other 
toolkits. 


Parameters: 
— widget : a GtkWidget 


— sensitive : TRUE to make the widget sensitive 


Returns: 


void 


6.22.2.111 void gtk_widget_set_size_request (GtkWidget « widget, gint width, gint height) 


Sets the minimum size of a widget; that is, the widget’s size request will be width by height. 


Parameters: 
— widget : a GtkWidget 
— width : width widget should request, or -1 to unset 


— height : height widget should request, or -1 to unset 


Returns: 


void 


6.22.2.112 void gtk_widget_set_state (GtkWidget « widget, GtkStateType state) 


This function is for use in widget implementations. 


Sets the state of a widget (insensitive, prelighted, etc.) Usually you should set the state using wrapper 
functions such as gtk_widget_set_sensitive(). 


Parameters: 

— widget : a GtkWidget 

< state : new state for widget 
Returns: 


void 
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6.22.2.113 void gtk_widget_set_style (GtkWidget « widget, GtkStyle ~ style) 


Sets the GtkStyle for a widget (widget->style). 
You probably don’t want to use this function; it interacts badly with themes, because themes work by 
replacing the GtkStyle. Instead, use gtk_widget_modify_style(). 
Parameters: 
— widget : a GtkWidget 
— style : a GtkStyle, or NULL to remove the effect of a previous gtk_widget_set_style() and go back 
to the default style 
Returns: 


void 


6.22.2.114 void gtk_widget_shape_combine_mask (GtkWidget « widget, GdkBitmap * 
shape_mask, gint offset_x, gint offset_y) 
Sets a shape for this widget’s GDK window. 


This allows for transparent windows etc., see gdk_window_shape_combine_mask() for more informa- 
tion.. 


Parameters: 
— widget : a GtkWidget 
— shape_mask : shape to be added, or NULL to remove an existing shape. 
—offset_x : X position of shape mask with respect to window. 


— offset_y : Y position of shape mask with respect to window. 


Returns: 


void 


6.22.2.115 void gtk_widget_show (GtkWidget x widget) 


Flags a widget to be displayed. 


Any widget that isn’t shown will not appear on the screen. If you want to show all the widgets in a container, 
it’s easier to call gtk_widget_show_all() on the container, instead of individually showing the widgets. 
Remember that you have to show the containers containing a widget, in addition to the widget itself, before 
it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other 
shown widgets are realized and mapped when their toplevel container is realized and mapped. 
Parameters: 


— widget : a GtkWidget 


Returns: 


void 
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6.22.2.116 void gtk_widget_show_all (GtkWidget * widget) 
Recursively shows a widget, and any child widgets (if the widget is a container). 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.117 void gtk_widget_show_now (GtkWidget « widget) 


Shows a widget. 


If the widget is an unmapped toplevel widget (i.e. a GtkWindow that has not yet been shown), enter the 
main loop and wait for the window to actually be mapped. Be careful; because the main loop is running, 
anything can happen during this function. anything can happen during this function. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.118 void gtk_widget_size_allocate (GtkWidget « widget, GtkAllocation « allocation) 


This function is only used by GtkContainer subclasses, to assign a size and position to their child widgets. 


Parameters: 
— widget : a GtkWidget 


< allocation : position and size to be allocated to widget 


Returns: 


void 


6.22.2.119 void gtk_widget_size_request (GtkWidget x widget, GtkRequisition x requisition) 


This function is typically used when implementing a GtkContainer subclass. 


Obtains the preferred size of a widget. The container uses this information to arrange its child widgets and 
decide what size allocations to give them with gtk_widget_size_allocate(). You can also call this function 
from an application, with some caveats. Most notably, getting a size request requires the widget to be 
associated with a screen, because font information may be needed. Multihead-aware applications should 
keep this in mind. Also remember that the size request is not necessarily the size a widget will actually be 
allocated. See also gtk_widget_get_child_requisition(). 
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Parameters: 
— widget : a GtkWidget 


— requisition : a GtkRequisition to be filled in 


Returns: 


void 


6.22.2.120 void gtk_widget_style_get (GtkWidget * widget, const gchar * first_property_name, ...) 
Gets the values of a multiple style properties of widget. 


Parameters: 
— widget : a GtkWidget 
— first_property_name : the name of the first property to get 


<—... ! pairs of property names and locations to return the property values, starting with the location 
for first_property_name, terminated by NULL. 


Returns: 


void 


6.22.2.121 void gtk_widget_style_get_property (GtkWidget « widget, const gchar x property_name, 
GValue x value) 


Gets the value of a style property of widget. 


Parameters: 
— widget : a GtkWidget 
— property_name : the name of a style property 


— value : location to return the property value 


Returns: 


void 


6.22.2.122 void gtk_widget_style_get_valist (GtkWidget x widget, const gchar x 
first_property_name, va_list var_args) 


Non-vararg variant of gtk_widget_style_get(). 


Used primarily by language bindings. 


Parameters: 
— widget : a GtkWidget 
— first_property_name : the name of the first property to get 
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— var_args : a va_list of pairs of property names and locations to return the property values, starting 
with the location for first_property_name. 


Returns: 


void 


6.22.2.123 void gtk_widget_thaw_child_notify (GtkWidget « widget) 


Reverts the effect of a previous call to gtk_widget_freeze_child_notify(. 


This causes all queued "child-notify" signals on widget to be emitted. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.124 gboolean gtk_widget_translate_coordinates (GtkWidget * src_widget, GtkWidget x 
dest_widget, gint src_x, gint src_y, gint « dest_x, gint x dest_y) 
Translate coordinates relative to src_widget’s allocation to coordinates relative to dest_widget’s allocations. 


In order to perform this operation, both widgets must be realized, and must share a common toplevel. 


Parameters: 
— widget : a GtkWidget 
— dest_widget : a GtkWidget 
< src_x : X position relative to src_widget 
< src_y : Y position relative to src_widget 
— dest_x : location to store X position relative to dest_widget 


> dest_y : location to store Y position relative to dest_widget 


Returns: 


FALSE if either widget was not realized, or there was no common ancestor. In this case, nothing is 
stored in *dest_x and *dest_y. Otherwise TRUE. 


6.22.2.125 void gtk_widget_unmap (GtkWidget « widget) 
This function is only for use in widget implementations. 
Causes a widget to be unmapped if it’s currently mapped. 
Parameters: 

— widget : a GtkWidget 


Returns: 


void 
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6.22.2.126 void gtk_widget_unparent (GtkWidget * widget) 


This function is only for use in widget implementations. 


Should be called by implementations of the remove method on GtkContainer, to dissociate a child from the 
container. 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.127 void gtk_widget_unrealize (GtkWidget x widget) 


This function is only useful in widget implementations. 


Causes a widget to be unrealized (frees all GDK resources associated with the widget, such as widget- 
>window). 


Parameters: 


— widget : a GtkWidget 


Returns: 


void 


6.22.2.128 void gtk_widget_unref (GtkWidget * widget) 


Decrements a reference to a widget. 


Inverse of gtk_widget_ref(). Equivalent to g_object_unref(). 


Parameters: 


— widget : a GtkWidget 
Returns: 


void 


6.22.3 Variable Documentation 
6.22.3.1 GtkAllocation _GtkWidget::allocation [inherited] 


The widget’s allocated size. 


6.22.3.2 guint GtkWidget::bg_transparent [inherited] 


whether to fill the widgets background 
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6.22.3.3 void(« _GtkWidgetClass::dispatch_child_properties_changed)(Gtk Widget «widget, guint 
n_pspecs, GParamSpec *xpspecs) [inherited] 


seldomly overidden 


6.22.3.4 gcharx GtkWidget::name [inherited] 


The widget’s name. 


If the widget does not have a name (the name is NULL), then its name (as returned by "gtk_widget_get_- 
name") is its class’s name. Among other things, the widget name is used to determine the style to use for a 
widget. 


6.22.3.5 GtkWidget« GtkWidget::parent [inherited] 


The widget’s parent. 


6.22.3.6 guintl6 _GtkWidget::private_flags [inherited] 


16 bits of internally used private flags. 


this will be packed into the same 4 byte alignment frame that state and saved_state go. we therefore don’t 
waste any new space on this. 


6.22.3.7 GtkRequisition GtkWidget::requisition [inherited] 


The widget’s desired size. 


6.22.3.8 guint8 GtkWidget::saved_state [inherited] 


The saved state of the widget. 


When a widget’s state is changed to GTK_STATE_INSENSITIVE via "gtk_widget_set_state" or "gtk_- 
widget_set_sensitive" the old state is kept around in this field. The state will be restored once the widget 
gets sensitive again. 


6.22.3.9 guint8 GtkWidget::state [inherited] 


The state of the widget. 


There are actually only 5 widget states (defined in "gtkenums.h"). 


6.22.3.10 GtkStylex GtkWidget::style [inherited] 


The style for the widget. 


The style contains the colors the widget should be drawn in for each state along with graphics contexts 
used to draw with and the font to use for text. 
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6.22.3.11 GdkWindow« _GtkWidget::window [inherited] 


The widget's window or its parent window if it does not have a window. 


(Which will be indicated by the GTK_NO_WINDOW flag being set). 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


210 Module Documentation 


6.23 Windows 


Modules 


e GtkDialog 


Dialog boxes are a convenient way to prompt the user for a small amount of input. 


e GtkWindow 


Toplevel window which can contain other widgets. 
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6.24 GtkDialog 


6.24.1 Detailed Description 


Dialog boxes are a convenient way to prompt the user for a small amount of input. 


Example to display a message, ask a question, or anything else that does not require extensive effort on the 
user's part. 


GTK+ treats a dialog as a window split vertically. The top section is a GtkVBox, and is where widgets 
such as a GtkLabel or a GtkEntry should be packed. The bottom area is known as the action_area. This 
1s generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or 
apply. The two areas are separated by a GtkHSeparator. 


GtkDialog boxes are created with a call to gtk_dialog_new() or gtk_dialog_new_with_buttons(). gtk_- 
dialog_new_with_buttons() is recommended; it allows you to set the dialog title, some convenient flags, 
and add simple buttons. 


If *dialog’ is a newly created dialog, the two primary areas of the window can be accessed as GTK_- 
DIALOG(dialog)->vbox and GTK_DIALOG(dialog)->action_area, as can be seen from the example, be- 
low. 


A ’modal’ dialog (that is, one which freezes the rest of the application from user input), can be created 
by calling gtk_window_set_modal() on the dialog. Use the GTK_WINDOW() macro to cast the widget 
returned from gtk_dialog_new() into a GtkWindow. When using gtk_dialog_new_with_buttons() you can 
also pass the GTK_DIALOG_MODAL flag to make a dialog modal. 


If you add buttons to GtkDialog using gtk_dialog_new_with_buttons(), gtk_dialog_add_button(), gtk_- 
dialog_add_buttons(), or gtk_dialog_add_action_widget(), clicking the button will emit a signal called 
"response" with a response ID that you specified. GTK+ will never assign a meaning to positive response 
IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the GtkRespon- 
seType enumeration (these all have values less than zero). Ifa dialog receives a delete event, the "response" 
signal will be emitted with a response ID of GTK_RESPONSE_DELETE_EVENT. 


If you want to block waiting for a dialog to return before returning control flow to your code, you can call 
gtk_dialog_run(). This function enters a recursive main loop and waits for the user to respond to the dialog, 
returning the response ID corresponding to the button the user clicked. 


For the simple dialog in the following example, in reality you'd probably use GtkMessageDialog to save 
yourself some effort. But you'd need to create the dialog contents manually if you had more than a simple 
message in the dialog. 


Simple GtkDialog usage. 


GtkWidget *hbox; 

GtkWidget x*label; 
GtkWidget *entry; 
GtkWidget «dialog; 


dialog = gtk_dialog_new_with_title("title"); 


hbox = gtk_hbox_new (FALSE, 0); 
label = gtk_label_new ("NEW"); 


gtk_misc_set_alignment (GTK_MISC (label), 0, 0.5); 
gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, TRUE, 0); 


entry = gtk_entry_new (); 
gtk_entry_set_max_length (GTK_ENTRY (entry), 50); 
gtk_entry_set_text (GTK_ENTRY (entry), "Hello"); 
tmp_pos = GTK_ENTRY (entry)->text_length; 
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gtk_editable_insert_text (GTK_EDITABLE (entry), " world", -1, 
gtk_box_pack_start (GTK_BOX (hbox), entry, TRUE, TRUE, 0); 


gtk_widget_show (hbox) ; 
gtk_widget_show (label); 
gtk_widget_show (entry); 


gtk_dialog_add_widget (GTK_DIALOG (dialog) , hbox) ; 
gtk_widget_show (dialog); 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkDialog 


GtkDialog instance structure. 


e struct _GtkDialogClass 
GtkDialogClass class. 


e struct _GtkDialogClass 
GtkDialogClass class. 


Enumerations 


e enum GtkDialogFlags 


Parameters for dialog construction. 


Functions 


e GType gtk_dialog_get_type (void) G_GNUC_CONST 
Return the Gtype of Dialog function. 


e GtkWidget x gtk_dialog_new_with_title (const gchar x*title) 


Create a new dialog with title. 


e GtkWidget x gtk_dialog_new (void) 


Creates a new dialog box. 


e void gtk_dialog_add_widget (GtkDialog «dialog, GtkWidget *widget) 
Add the widget like label, entry, icon, etc. 


e GtkWidget x gtk_dialog_get_softkeybar (GtkDialog «dialog) 
Gets the value set by softkey widget. 


&tmp_pos) ; 


e void gtk_dialog_set_softkeybar (GtkDialog «dialog, GtkSoftkeyPosition position, gchar *softkey_- 
name, GtkWidget *softkey_icon, GtkSoftkeyActionType softkey_action_type, gpointer action, 


gpointer user_data) 
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Sets the value set by softkey widget. 


e void gtk_dialog_set_width (GtkDialog *dialog, gint width) 
Sets the Width of the dialog. 


e gint gtk_dialog_get_width (GtkDialog *dialog) 
Returns the Width of the dialog. 


e gboolean gtk_dialog_set_title (GtkDialog «dialog, const gchar title) 


Set the title of dialog widget. 


e G_CONST_RETURN gchar * gtk dialog get_title (GtkDialog «dialog) 
Get the title of dialog widget. 


e GtkWidget * gtk dialog _new_with_buttons (const gchar title, GtkWindow parent, GtkDi- 
alogFlags flags, const gchar «first_button_text,...) 


Creates a new GtkDialog with title title (or NULL for the default title; see gtk_window_set_title()) and 
transient parent parent (or NULL for none; see gtk_window_set_transient_for()). 


e void gtk_dialog_add_action_widget (GtkDialog «dialog, GtkWidget «child, gint response_id) 


Adds an activatable widget to the action area of a GtkDialog, connecting a signal handler that will emit the 
"response" signal on the dialog when the widget is activated. 


e GtkWidget * gtk_dialog_add_button (GtkDialog «dialog, const gchar *button_text, gint response_- 
id) 


Adds a button with the given text (or a stock button, if button_text is a stock ID) and sets things up so that 
clicking the button will emit the "response" signal with the given response_id. 


e void gtk_dialog_add_buttons (GtkDialog «dialog, const gchar x*first_button_text,...) G_GNUC_- 
NULL_TERMINATED 


Adds more buttons, same as calling gtk_dialog_add_button() repeatedly. 


e void gtk_dialog_set_response_sensitive (GtkDialog «dialog, gint response_id, gboolean setting) 


Calls gtk_widget_set_sensitive (widget, setting) for each widget in the dialog’s action area with the given 
response_id. 


e void gtk_dialog_set_default_response (GtkDialog *dialog, gint response_id) 


Sets the last widget in the dialog’s action area with the given response_id as the default widget for the 
dialog. 


e gint gtk_dialog_get_response_for_widget (GtkDialog «dialog, GtkWidget *widget) 


Gets the response id of a widget in the action area of a dialog. 


e void gtk_dialog_set_has_separator (GtkDialog dialog, gboolean setting) 


[Deprecated] Sets whether the dialog has a separator above the buttons. 


e gboolean gtk_dialog_get_has_separator (GtkDialog *dialog) 


[Deprecated] Accessor for whether the dialog has a separator. 


e gboolean gtk_alternative_dialog_button_order (GdkScreen *screen) 


Returns TRUE if dialogs are expected to use an alternative button order on the screen screen. 
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e void gtk_dialog_set_alternative_button_order (GtkDialog *dialog, gint first_response_id,...) 


Sets an alternative button order. 


e void gtk_dialog_set_alternative_button_order_from_array (GtkDialog dialog, gint n_params, gint 
*new_order) 


Sets an alternative button order. 


e void gtk_dialog_response (GtkDialog *dialog, gint response_id) 


Emits the "response" signal with the given response ID. 


e gint gtk_dialog_run (GtkDialog «dialog) 


Blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed. 


6.24.2 Enumeration Type Documentation 
6.24.2.1 enum GtkDialogFlags 


Parameters for dialog construction. 


6.24.3 Function Documentation 
6.24.3.1 gboolean gtk_alternative_dialog_button_order (GdkScreen x screen) 


Returns TRUE if dialogs are expected to use an alternative button order on the screen screen. 


See gtk_dialog_set_alternative_button_order() for more details about alternative button order. If you need 
to use this function, you should probably connect to the notify:gtk-alternative-button-order signal on the 
GtkSettings object associated to screen, in order to be notified if the button order setting changes. 


Parameters: 


< screen a GdkScreen, or NULL to use the default screen 


Returns: 


Whether the alternative button order should be used 


6.24.3.2 void gtk_dialog_add_action_widget (GtkDialog « dialog, GtkWidget x child, gint 
response_id) 


Adds an activatable widget to the action area of a GtkDialog, connecting a signal handler that will emit the 
"response" signal on the dialog when the widget is activated. 


The widget is appended to the end of the dialog’s action area. If you want to add a non-activatable widget, 
simply pack it into the action_area field of the GtkDialog struct. 


Parameters: 


— dialog a GtkDialog 


— child an activatable widget 
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— response_id response ID for child 


Returns: 


void 


6.24.3.3 GtkWidget* gtk_dialog_add_button (GtkDialog « dialog, const gchar x button_text, gint 
response_id) 


Adds a button with the given text (or a stock button, if button_text is a stock ID) and sets things up so that 
clicking the button will emit the "response" signal with the given response_id. 

The button is appended to the end of the dialog’s action area. The button widget is returned, but usually 
you don't need it. 

Parameters: 


— dialog a GtkDialog. 
— button_text text of button, or stock ID 


— response_id response ID for the button 


Returns: 


the button widget that was added 


6.24.3.4 void gtk_dialog_add_buttons (GtkDialog = dialog, const gchar x first_button_text, ...) 


Adds more buttons, same as calling gtk_dialog_add_button() repeatedly. 


The variable argument list should be NULL-terminated as with gtk dialog new_with_buttons(). Each 
button must have both text and response ID. 


Parameters: 
— dialog a GtkDialog. 
— first_button_text button text or stock ID 


— ... response ID for first button, then more text-response_id pairs 


Returns: 


void 


6.24.3.5 void gtk_dialog_add_widget (GtkDialog « dialog, GtkWidget « widget) 
Add the widget like label, entry, icon, etc. 


Parameters: 
— dialog a GtkDialog 


— widget an activatable widget 
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Returns: 
void 
Remarks: 


content area container. Application user can add various widget in it. content area can use, 
vbox(default) or hbox 


Since 


LIMO R1 


6.24.3.6 gboolean gtk_dialog_get_has_separator (GtkDialog x dialog) 


[Deprecated] Accessor for whether the dialog has a separator. 


Parameters: 


— dialog a GtkDialog 


Returns: 


TRUE if the dialog has a separator 


Deprecated 
LIMO R1 


6.24.3.7 gint gtk_dialog_get_response_for_widget (GtkDialog * dialog, GtkWidget « widget) 
Gets the response id of a widget in the action area of a dialog. 


Parameters: 


— dialog a GtkDialog. 


— widget a widget in the action area of dialog 


Returns: 


the response id of widget, or GTK_RESPONSE_NONE if widget doesn't have a response id set. 


6.24.3.8 GtkWidget* gtk_dialog_get_softkeybar (GtkDialog « dialog) 


Gets the value set by softkey widget. 


Parameters: 


— dialog a GtkDialog 


Returns: 


the GtkSoftkey widget 


Since 


LIMO RI 
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6.24.3.9 G_CONST_RETURN gchar gtk_dialog_get_title (GtkDialog * dialog) 


Get the title of dialog widget. 


Parameters: 


— dialog GtkDialog 


Returns: 


title of dialog 


Since 


LIMO RI 


6.24.3.10 GType gtk_dialog_get_type (void) 


Return the Gtype of Dialog function. 


Returns: 


GType Type 


6.24.3.11 gint gtk_dialog_get_width (GtkDialog x dialog) 


Returns the Width of the dialog. 


Parameters: 


— dialog a GtkDialog 


Returns: 


width of the gtk dialog 


Since 


LIMO R1 


6.24.3.12 GtkWidget» gtk_dialog_new (void) 


Creates a new dialog box. 


Widgets should not be packed into this Gtk Window directly, but into the vbox and action_area, as described 


above. 


Returns: 


anew GtkDialog. 
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6.24.3.13 GtkWidget» gtk_dialog_new_with_buttons (const gchar = title, GtkWindow + parent, 
GtkDialogFlags flags, const gchar + first_button_text, ...) 


Creates a new GtkDialog with title title (or NULL for the default title; see gtk_window_set_title()) and 
transient parent parent (or NULL for none; see gtk_window_set_transient_for()). 


The flags argument can be used to make the dialog modal (GTK_DIALOG_MODAL) and/or to have 
it destroyed along with its transient parent (GTK_DIALOG_DESTROY_WITH_PARENT). After flags, 
button text/response ID pairs should be listed, with a NULL pointer ending the list. Button text can be either 
a stock ID such as GTK_STOCK_OK, or some arbitrary text. A response ID can be any positive number, 
or one of the values in the GtkResponseType enumeration. If the user clicks one of these dialog buttons, 
GtkDialog will emit the "response" signal with the corresponding response ID. If a GtkDialog receives the 
"delete_event" signal, it will emit "response" with a response ID of GTK_RESPONSE_DELETE_EVENT. 
However, destroying a dialog does not emit the "response" signal; so be careful relying on "response" when 
using the GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, so the first 
button in the list will be the leftmost button in the dialog. Here’s a simple example: 


GtkWidget *dialog = gtk_dialog_new_with_buttons ("My dialog", 
main_app_window, 
GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT, 
GTK_STOCK_OK, 
GTK_RESPONSE_ACCEPT, 
GTK_STOCK_CANCEL, 
GTK_RESPONSE_REJECT, 
NULL) ; 


Parameters: 


— title Title of the dialog, or NULL 

— parent Transient parent of the dialog, or NULL 

— flags from GtkDialogFlags 

— first_button_text stock ID or text to go in first button, or NULL 

— ... response ID for first button, then additional buttons, ending with NULL 


Returns: 


a new GtkDialog 


6.24.3.14 GtkWidget» gtk_dialog_new_with_title (const gchar + title) 


Create a new dialog with title. 
Title must be entered if needed. 
Parameters: 


— title : a title to the dialog 


Returns: 


a new gtkdialog widget. 


Note: 


Tf title is null then no title dialog is created. 


Since 


LIMO R1 
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6.24.3.15 void gtk_dialog_response (GtkDialog * dialog, gint response_id) 


Emits the "response" signal with the given response ID. 


Used to indicate that the user has responded to the dialog in some way; typically either you or gtk_dialog_- 
run() will be monitoring the "response" signal and take appropriate action. 


Parameters: 


— dialog a GtkDialog. 


— response_id response ID 


Returns: 


void 


6.24.3.16 gint gtk_dialog_run (GtkDialog x dialog) 


Blocks in a recursive main loop until the dialog either emits the response signal, or is destroyed. 


If the dialog is destroyed during the call to gtk_dialog run(), gtk_dialog_returns GTK_RESPONSE_- 
NONE. Otherwise, it returns the response ID from the "response" signal emission. Before entering the 
recursive main loop, gtk_dialog_run() calls gtk_widget_show() on the dialog for you. Note that you still 
need to show any children of the dialog yourself. 


Parameters: 


— dialog a GtkDialog Returns response_id 


6.24.3.17 void gtk_dialog_set_alternative_button_order (GtkDialog * dialog, gint first_response_id, 
s) 


Sets an alternative button order. 


If the gtk-alternative-button-order setting is set to TRUE, the dialog buttons are reordered according to the 
order of the response ids passed to this function. By default, GTK+ dialogs use the button order advocated 
by the Gnome Human Interface Guidelines with the affirmative button at the far right, and the cancel 
button left of it. But the builtin GTK+ dialogs and GtkMessageDialogs do provide an alternative button 
order, which is more suitable on some platforms, e.g. Windows. Use this function after adding all the 
buttons to your dialog, as the following example shows: 


cancel_button = gtk_dialog_add_button (GTK_DIALOG (dialog), 
GTK_STOCK_CANCEL, 
GTK_RESPONSE_CANCEL) ; 


ok_button = gtk_dialog_add_button (GTK_DIALOG (dialog), 
GTK_STOCK_OK, 
GTK_RESPONSE_OK) ; 


gtk_widget_grab_default (ok_button); 

help_button = gtk_dialog_add_button (GTK_DIALOG (dialog), 
GTK_STOCK_HELP, 
GTK_RESPONSE_HELP); 


gtk_dialog_set_alternative_button_order (GTK_DIALOG (dialog), 
GTK_RESPONSE_OK, 
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GTK_RESPONSE_CANCEL, 
GTK_RESPONSE_HELP, 
=) 


Parameters: 
— dialog a GtkDialog. 
— first_response_id a response id used by one dialog’s buttons 


— ... a list of more response ids of dialog’s buttons, terminated by -1 


Returns: 


void 


6.24.3.18 void gtk dialog set_alternative_button_order_from_array (GtkDialog « dialog, gint 
n_params, gint x new_order) 


Sets an alternative button order. 
If the gtk-alternative-button-order setting is set to TRUE, the dialog buttons are reordered according to the 
order of the response ids in new_order. See gtk_dialog_set_alternative_button_order() for more informa- 
tion. This function is for use by language bindings. 
Parameters: 

— dialog a GtkDialog. 

— n_params the number of response ids in new_order 


— new_order an array of response ids of dialog’s buttons 


Returns: 


void 


6.24.3.19 void gtk_dialog_set_default_response (GtkDialog « dialog, gint response_id) 


Sets the last widget in the dialog’s action area with the given response_id as the default widget for the 
dialog. 


Pressing "Enter" normally activates the default widget. 


Parameters: 
— dialog a GtkDialog. 


— response_id a response ID 


Returns: 


void 
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6.24.3.20 void gtk_dialog_set_has_separator (GtkDialog « dialog, gboolean setting) 


[Deprecated] Sets whether the dialog has a separator above the buttons. 


TRUE by default. 


Parameters: 


— dialog a GtkDialog. 
— setting TRUE to have a separator 


Returns: 


void 
Deprecated 
LIMO R1 


6.24.3.21 void gtk_dialog_set_response_sensitive (GtkDialog « dialog, gint response_id, gboolean 
setting) 


Calls gtk_widget_set_sensitive (widget, setting) for each widget in the dialog’s action area with the given 
response_id. 


A convenient way to sensitize/desensitize dialog buttons. 


Parameters: 


— dialog a GtkDialog. 
— response_id a response ID 


— setting TRUE for sensitive 


Returns: 


void 


6.24.3.22 void gtk_dialog_set_softkeybar (GtkDialog * dialog, GtkSoftkeyPosition position, gchar 
x softkey_name, GtkWidget « softkey_icon, GtkSoftkeyActionType softkey_action_type, 
gpointer action, gpointer user_data) 


Sets the value set by softkey widget. 


Parameters: 


— dialog a GtkDialog 

— position position of soft key bar. 
— softkey name. 

< softkey icon. 

— softkey action type. 

— gtkmenu. 


< callback function. 
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Returns: 


void 


Since 


LIMO RI 


6.24.3.23 gboolean gtk_dialog_set_title (GtkDialog x dialog, const gchar x title) 
Set the title of dialog widget. 


Parameters: 
— dialog GtkDialog 
— title Title of dialog widget 


Returns: 


TRUE if the title is set 


Since 


LIMO R1 


6.24.3.24 void gtk_dialog_set_width (GtkDialog * dialog, gint width) 
Sets the Width of the dialog. 


Parameters: 
dialog [in] a GtkDialog 
width [in] width of the dialog. 


Returns: 


void 


Since 


LIMO RI 
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6.25 GtkWindow 


6.25.1 Detailed Description 


Toplevel window which can contain other widgets. 


Figure 6.2: GtkWindow 


Data Structures 


e struct _GtkWindow 


GtkWindow instance structure. 


e struct _GtkWindowClass 


GtkWindow instance class structure. 


e struct _GtkWindowGroup 


GtkWindowGroup instance structure. 


e struct _GtkWindowGroupClass 


GtkWindowGroup instance class structure. 


Functions 


e GtkWidget * gtk_window_new (GtkWindowType type) 


Creates a new GtkWindow, which is a toplevel window that can contain other widgets. 


e void gtk_window_set_title (Gtk Window *window, const gchar title) 


Sets the title of the GtkWindow. 


e G_CONST_RETURN gchar x gtk _window_get_title (GtkWindow *window) 


Retrieves the title of the window. 
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void gtk_window_set_wmclass (GtkWindow *window, const gchar *wmclass_name, const gchar 
*«wmclass_class) 


Don't use this function. 


void gtk_window_set_role (GtkWindow *window, const gchar «role) 


This function is only useful on X11, not with other GTK+ targets. 


G_CONST_RETURN gchar x gtk_window_get_role (Gtk Window *window) 


Returns the role of the window. 


void gtk_window_add_accel_group (GtkWindow *window, GtkAccelGroup *accel_group) 


Associate accel_group with window, such that calling gtk_accel_groups_activate() on window will activate 
accelerators in accel_group. 


void gtk_window_remove_accel_group (GtkWindow «window, GtkAccelGroup *accel_group) 


Reverses the effects of gtk_window_add_accel_group(). 


void gtk_window_set_position (GtkWindow «window, GtkWindowPosition position) 


Sets a position constraint for this window. 


gboolean gtk_window_activate_focus (GtkWindow *window) 


Activates the current focused widget within the window. 


void gtk_window_set_focus (GtkWindow «window, GtkWidget *focus) 


If focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. 


GtkWidget x gtk_window_get_focus (GtkWindow *window) 


Gets the value set by gtk_window_set_focus_on_map(). 


void gtk_window_set_default (GtkWindow «window, GtkWidget *default_widget) 


This function sets or unsets the default widget for a GtkWindow about. 


gboolean gtk_window_activate_default (GtkWindow *window) 


Activates the default widget for the window, unless the current focused widget has been configured to receive 
the default action (see GTK_RECEIVES_DEFAULT in GtkWidgetFlags), in which case the focused widget 
is activated. 


void gtk_window_set_transient_for (GtkWindow «window, GtkWindow *parent) 


Dialog windows should be set transient for the main application window they were spawned from. 


GtkWindow * gtk_window_get_transient_for (GtkWindow *window) 


Fetches the transient parent for this window. 


void gtk_window_set_type_hint (GtkWindow *window, GdkWindowTypeHint hint) 


This function sets the type hint for the window, So, you allow the window manager to decorate and handle 
the window in a way which is suitable to the function of the window in your application. 


GdkWindowTypeHint gtk_window_get_type_hint (GtkWindow *window) 
Gets the type hint for this window. 


void gtk_window_set_skip_taskbar_hint (GtkWindow «window, gboolean setting) 
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Windows may set a hint asking the desktop environment not to display the window in the task bar. 


e gboolean gtk_window_get_skip_taskbar_hint (GtkWindow *window) 


Gets the value set by gtk_window_set_skip_taskbar_hint(). 


e void gtk_window_set_skip_pager_hint (GtkWindow *window, gboolean setting) 


Windows may set a hint asking the desktop environment not to display the window in the pager. 


e gboolean gtk_window_get_skip_pager_hint (GtkWindow *window) 


Returns the value set by gtk_window_set_skip_pager_hint(). 


e void gtk_window_set_urgency_hint (GtkWindow *window, gboolean setting) 


Windows may set a hint asking the desktop environment to draw the users attention to the window. 


e gboolean gtk_window_get_urgency_hint (GtkWindow *window) 


Gets the value set by gtk_window_set_urgency_hint(). 


e void gtk_window_set_accept_focus (GtkWindow *window, gboolean setting) 


Windows may set a hint asking the desktop environment not to receive the input focus. 


e gboolean gtk_window_get_accept_focus (GtkWindow *window) 


Gets the value set by gtk_window_set_accept_focus(). 


e void gtk_window_set_focus_on_map (GtkWindow *window, gboolean setting) 


Windows may set a hint asking the desktop environment not to receive the input focus when the window is 
mapped. 


e gboolean gtk_window_get_focus_on_map (GtkWindow *window) 


Gets the value set by gtk_window_set_focus_on_map(). 


e void gtk_window_set_destroy_with_parent (GtkWindow «window, gboolean setting) 


If setting is TRUE, then destroying the transient parent of window will also destroy window itself. 


e gboolean gtk_window_get_destroy_with_parent (GtkWindow window) 


Returns whether the window will be destroyed with its transient parent. 


e void gtk_window_set_resizable (Gtk Window «window, gboolean resizable) 


Sets whether the user can resize a window. 


e gboolean gtk_window_get_resizable (GtkWindow *window) 


Gets the value set by gtk_window_set_resizable(). 


e void gtk_window_set_gravity (GtkWindow *window, GdkGravity gravity) 


Window gravity defines the meaning of coordinates passed to gtk_window_move(). 


e GdkGravity gtk_window_get_gravity (GtkWindow *window) 


Gets the value set by gtk_window_set_gravity(). 


e void gtk_window_set_geometry_hints (GtkWindow «window, GtkWidget *geometry_widget, Gd- 
kGeometry «geometry, GdkWindowHints geom_mask) 
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This function sets up hints about how a window can be resized by the user. 


void gtk_window_set_screen (GtkWindow *window, GdkScreen *screen) 


Sets the GdkScreen where the window is displayed; if the window is already mapped, it will be unmapped, 
and then remapped on the new screen. 


GdkScreen * gtk_window_get_screen (GtkWindow *window) 


Returns the GdkScreen associated with window. 


gboolean gtk_window_is_active (GtkWindow *window) 


Returns whether the window is part of the current active toplevel. 


gboolean gtk_window_has_toplevel_focus (GtkWindow *window) 


Returns whether the input focus is within this GtkWindow. 


void gtk_window_set_has_frame (GtkWindow *window, gboolean setting) 


If this function is called on a window with setting of TRUE, before it is realized or showed, it will have a 
"frame" window around window->window, accessible in window->frame. 


gboolean gtk_window_get_has_frame (GtkWindow *window) 


Accessor for whether the window has a frame window exterior to window->window. 


void gtk_window_set_frame_dimensions (GtkWindow *window, gint left, gint top, gint right, gint 
bottom) 


(Note: this is a special-purpose function intended for the framebuffer port; see gtk_window_set_has_- 


frame(). 


void gtk_window_get_frame_dimensions (GtkWindow *window, gint x*left, gint *top, gint xright, 
gint xbottom) 


(Note: this is a special-purpose function intended for the framebuffer port; see gtk_window_set_has_- 


frame(). 


void gtk_window_set_decorated (GtkWindow «window, gboolean setting) 


This function is used to set the decoration property of the window.By default, windows are decorated with a 
title bar, resize controls, etc. 


gboolean gtk_window_get_decorated (GtkWindow *window) 


Returns whether the window has been set to have decorations such as a title bar via gtk_window_set_- 
decorated). 


void gtk_window_set_deletable (GtkWindow *window, gboolean setting) 


By default, windows have a close button in the window frame. 


gboolean gtk_window_get_deletable (Gtk Window *window) 


Returns whether the window has been set to have a close button via gtk_window_set_deletable(). 


void gtk_window_set_icon_list (GtkWindow *window, GList «list) 


Sets up the icon representing a GtkWindow. 


GList * gtk_window_get_icon_list (GtkWindow *window) 


Retrieves the list of icons set by gtk_window_set_icon_list(). 
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e void gtk_window_set_icon (GtkWindow *window, GdkPixbuf +icon) 


Sets up the icon representing a GtkWindow. 


e void gtk_window_set_icon_name (GtkWindow *window, const gchar xname) 


Sets the icon for the window from a named themed icon. 


e gboolean gtk_window_set_icon_from_file (GtkWindow *window, const gchar x*filename, GError 
**err) 


Sets the icon for window. 


e GdkPixbuf x gtk_window_get_icon (GtkWindow *window) 


Gets the value set by gtk_window_set_icon() (or if you've called gtk_window_set_icon_list(), gets the first 
icon in the icon list). 


e G_CONST_RETURN gchar x gtk_window_get_icon_name (GtkWindow *window) 


Returns the name of the themed icon for the window, see gtk_window_set_icon_name( ). 


e void gtk_window_set_default_icon_list (GList xlist) 


Sets an icon list to be used as fallback for windows that haven't had gtk_window_set_icon_list() called on 
them to set up a window-specific icon list. 


e GList x gtk_window_get_default_icon_list (void) 


Gets the value set by gtk_window_set_default_icon_list(). 


e void gtk_window_set_default_icon (GdkPixbuf *icon) 


Sets an icon to be used as fallback for windows that haven’t had gtk_window_set_icon() called on them 
from a pixbuf. 


e void gtk_window_set_default_icon_name (const gchar xname) 


Sets an icon to be used as fallback for windows that haven’t had gtk_window_set_icon_list() called on them 
from a named themed icon, see gtk_window_set_icon_name(). 


e gboolean gtk_window_set_default_icon_from_file (const gchar «filename, GError xxerr) 


Sets an icon to be used as fallback for windows that haven’t had gtk_window_set_icon_list() called on them 
from a file on disk. 


e void gtk_window_set_auto_startup_notification (gboolean setting) 


By default, after showing the first GtkWindow, GTK+ calls gdk_notify_startup_complete(). 


e void gtk_window_set_modal (GtkWindow «window, gboolean modal) 


Sets a window modal or non-modal. 


e gboolean gtk_window_get_modal (Gtk Window *window) 


Returns whether the window is modal. 


e GList * gtk_window_list_toplevels (void) 


Returns a list of all existing toplevel windows. 


e void gtk_window_add_mnemonic (GtkWindow «window, guint keyval, GtkWidget xtarget) 


[Deprecated] Adds a mnemonic to this window. 
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void gtk_window_remove_mnemonic (GtkWindow *window, guint keyval, GtkWidget xtarget) 


[Deprecated] Removes a mnemonic from this window. 


gboolean gtk_window_mnemonic_activate (GtkWindow *window, guint keyval, GdkModifierType 
modifier) 


[Deprecated] Activates the targets associated with the mnemonic. 


void gtk_window_set_mnemonic_modifier (GtkWindow *window, GdkModifierType modifier) 


[Deprecated] Sets the mnemonic modifier for this window. 


GdkModifierType gtk_window_get_mnemonic_modifier (GtkWindow *window) 


[Deprecated] Returns the mnemonic modifier for this window. 


gboolean gtk_window_activate_key (GtkWindow *window, GdkEventKey *event) 


Activates mnemonics and accelerators for this GtkWindow. 


gboolean gtk_window_propagate_key_event (GtkWindow *window, GdkEventKey *event) 


Propagate a key press or release event to the focus widget and up the focus container chain until a widget 
handles event. 


void gtk_window_present (GtkWindow *window) 


Presents a window to the user. 


void gtk_window_present_with_time (GtkWindow «window, guint32 timestamp) 


Presents a window to the user in response to a user interaction. 


void gtk_window_iconify (GtkWindow *window) 


[Deprecated] Asks to iconify (that is minimize) the specified window. 


void gtk_window_deiconify (GtkWindow *window) 


[Deprecated] Asks to deiconify (that is unminimize) the specified window. 


void gtk_window_stick (GtkWindow *window) 


Asks to stick window, which means that it will appear on all user desktops. 


void gtk_window_unstick (GtkWindow *window) 


Asks to unstick window, which means that it will appear on only one of the user’s desktops. 


void gtk_window_maximize (GtkWindow *window) 


Asks to maximize window, so that it becomes full-screen. 


void gtk_window_unmaximize (GtkWindow *window) 


Asks to unmaximize window. 


void gtk_window_fullscreen (GtkWindow *window) 


Asks to place window in the fullscreen state. 


void gtk_window_unfullscreen (Gtk Window *window) 


Asks to toggle off the fullscreen state for window. 
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e void gtk_window_set_keep_above (GtkWindow *window, gboolean setting) 


Asks to keep window above, so that it stays on top. 


e void gtk_window_set_keep_below (GtkWindow «window, gboolean setting) 


Asks to keep window below, so that it stays in bottom. 


e void gtk_window_begin_resize_drag (GtkWindow *window, GdkWindowEdge edge, gint button, 
gint root_x, gint root_y, guint32 timestamp) 


[Deprecated] Starts resizing a window. 


e void gtk_window_begin_move_drag (GtkWindow *window, gint button, gint root_x, gint root_y, 
guint32 timestamp) 


[Deprecated] Starts moving a window. 


e void gtk_window_set_default_size (GtkWindow «window, gint width, gint height) 


Sets the default size of a window. 


e void gtk_window_get_default_size (GtkWindow «window, gint xwidth, gint height) 


Gets the default size of the window. 


e void gtk_window_resize (GtkWindow window, gint width, gint height) 


Resizes the window as if the user had done so, obeying geometry constraints. The default geometry constraint 
is that windows may not be smaller than their size request; to override this constraint, call gtk_widget_set_- 
size_request() to set the window’s request to a smaller value. 


e void gtk_window_get_size (GtkWindow «window, gint «width, gint xheight) 


Obtains the current size of window. 


e void gtk_window_move (GtkWindow «window, gint x, gint y) 


Asks the window manager to move window to the given position. 


e void gtk_window_get_position (GtkWindow *window, gint *root_x, gint *root_y) 


This function returns the position you need to pass to gtk_window_move() to keep window in its current 
position. 


e gboolean gtk_window_parse_geometry (GtkWindow «window, const gchar *geometry) 


Parses a standard X Window System geometry string - see the manual page for X (type ’man X”) for details 
on this. 


e GtkWindowGroup * gtk_window_get_group (GtkWindow *window) 


Returns the group for window or the default group, if window is NULL or if window does not have an 
explicit window group. 


e void gtk_window_reshow_with_initial_size (Gtk Window *window) 


Hides window, then reshows it, resetting the default size and position of the window. 


e GType gtk_window_group_get_type (void) G_GNUC_CONST 
Window group type. 


e GtkWindowGroup * gtk_window_group_new (void) 
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Creates new window group. 


void  gtk_window_group_add_window  (GtkWindowGroup  xwindow_group, GtkWindow 
*window) 


Adds a window to a GtkWindowGroup. 


void gtk_window_group_remove_window (GtkWindowGroup *window_group, GtkWindow 
*window) 


Removes a window from GtkWindowGroup. 


void gtk_window_set_bg_transparent (GtkWindow *window, gboolean transparent) 


Sets the window background as transparent. 


gboolean gtk_window_is_bg_transparent (Gtk Window *window) 


Returns whether the Window is Transparent or Opaque to its parant. 


6.25.2 Function Documentation 


6.25.2.1 gboolean gtk_window_activate_default (GtkWindow « window) 
Activates the default widget for the window, unless the current focused widget has been configured to re- 


ceive the default action (see GTK_RECEIVES_DEFAULT in GtkWidgetFlags), in which case the focused 
widget is activated. 


Parameters: 


< window : a GtkWindow 


Returns: 


TRUE if a widget got activated. 


6.25.2.2 gboolean gtk_window_activate_focus (GtkWindow * window) 


Activates the current focused widget within the window. 


Parameters: 


< window : a GtkWindow 


Returns: 


TRUE if a widget got activated 


6.25.2.3 gboolean gtk_window_activate_key (GtkWindow x window, GdkEventKey x event) 


Activates mnemonics and accelerators for this Gtk Window. 


This is normally called by the default key_press_event handler for toplevel windows, however in some cases 
it may be useful to call this directly when overriding the standard key handling for a toplevel window. 
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Parameters: 


— window : a GtkWindow 


— event : a GdkEventKey 


Returns: 


TRUE if a mnemonic or accelerator was found and activated. 


6.25.2.4 void gtk_window_add_accel_group (GtkWindow x window, GtkAccelGroup * 
accel_group) 


Associate accel_group with window, such that calling gtk_accel_groups_activate() on window will activate 
accelerators in accel_group. 
Parameters: 


< window : window to attach accelerator group to 


— accel_group : a GtkAccelGroup 


Returns: 


void 


6.25.2.5 void gtk_window_add_mnemonic (GtkWindow * window, guint keyval, GtkWidget x 
target) 


[Deprecated] Adds a mnemonic to this window. 


Parameters: 


— window : a GtkWindow 
— keyval : the mnemonic 


— target : the widget that gets activated by the mnemonic 


Returns: 
void 
Deprecated 
LIMO RI 


6.25.2.6 void gtk_window_begin_move_drag (GtkWindow « window, gint button, gint root_x, gint 
root_y, guint32 timestamp) 


[Deprecated] Starts moving a window. 


This function is used if an application has window movement grips. When GDK can support it, the window 
movement will be done using the standard mechanism for the window manager or windowing system. 
Otherwise, GDK will try to emulate window movement, potentially not all that well, depending on the 
windowing system. 
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Parameters: 


— window : a GtkWindow 

— button : mouse button that initiated the drag 

— root_x : X position where the user clicked to initiate the drag, in root window coordinates 
< root_y : Y position where the user clicked to initiate the drag 


— timestamp : timestamp from the click event that initiated the drag 


Returns: 
void 
Deprecated 
LIMO R1 


6.25.2.7 void gtk_window_begin_resize_drag (GtkWindow « window, GdAkWindowEdge edge, gint 
button, gint root_x, gint root_y, guint32 timestamp) 
[Deprecated] Starts resizing a window. 


This function is used if an application has window resizing controls. When GDK can support it, the resize 
will be done using the standard mechanism for the window manager or windowing system. Otherwise, 
GDK will try to emulate window resizing, potentially not all that well, depending on the windowing sys- 
tem. 


Parameters: 


— window : a GtkWindow 

— edge : position of the resize control 

— button : mouse button that initiated the drag 

— root_x : X position where the user clicked to initiate the drag, in root window coordinates 
— root_y : Y position where the user clicked to initiate the drag 


— root_y : Y position where the user clicked to initiate the drag 
Returns: 

void 
Deprecated 

LIMO RI 


6.25.2.8 void gtk_window_deiconify (GtkWindow = window) 


[Deprecated] Asks to deiconify (that is unminimize) the specified window. 


Note that you shouldn’t assume the window is definitely deiconified afterward, because other entities (e.g. 
the user or window manager) could iconify it again before your code which assumes deiconification gets 
to run. You can track iconification via the "window_state_event" signal on GtkWidget. 


Parameters: 


< window a GtkWindow 
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Returns: 


void 


Deprecated 
LIMO R1 


6.25.2.9 void gtk_window_fullscreen (GtkWindow * window) 


Asks to place window in the fullscreen state. 


Note that you shouldn’t assume the window is definitely full screen afterward, because other entities (e.g. 
the user or window manager) could unfullscreen it again, and not all window managers honor requests to 
fullscreen windows. But normally the window will end up fullscreen. Just don’t write code that crashes if 
not. You can track maximization via the "window_state_event" signal on Gtk Widget. 


Parameters: 


< window a GtkWindow 


Returns: 


void 


6.25.2.10 gboolean gtk_window_get_accept_focus (GtkWindow x window) 


Gets the value set by gtk_window_set_accept_focus(). 


Parameters: 


< window a GtkWindow 


Returns: 


TRUE if window should receive the input focus 


6.25.2.11 gboolean gtk_window_get_decorated (GtkWindow * window) 


Returns whether the window has been set to have decorations such as a title bar via gtk_window_set_- 
decorated(). 


Parameters: 


< window a GtkWindow 


Returns: 


TRUE if the window has been set to have decorations 
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6.25.2.12 GList« gtk_window_get_default_icon_list (void) 


Gets the value set by gtk_window_set_default_icon_list(). 


The list is a copy and should be freed with g_list_free(), but the pixbufs in the list have not had their 
reference count incremented. 


Returns: 


copy of default icon list 


6.25.2.13 void gtk_window_get_default_size (GtkWindow * window, gint x width, gint x height) 


Gets the default size of the window. 


A value of -1 for the width or height indicates that a default size has not been explicitly set for that dimen- 
sion, so the "natural" size of the window will be used. 


Parameters: 


— window : a GtkWindow 
— width : location to store the default width, or NULL 
— height : location to store the default height, or NULL 


Returns: 


void 


6.25.2.14 gboolean gtk_window_get_deletable (GtkWindow x window) 
Returns whether the window has been set to have a close button via gtk_window_set_deletable(). 


Parameters: 


— window : a GtkWindow 


Returns: 


TRUE if the window has been set to have a close button 


6.25.2.15 gboolean gtk_window_get_destroy_with_parent (GtkWindow x window) 


Returns whether the window will be destroyed with its transient parent. 


See gtk_window_set_destroy_with_parent(). 


Parameters: 


— window a GtkWindow 


Returns: 


TRUE if the window will be destroyed with its transient parent. 
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6.25.2.16 GtkWidget« gtk_window_get_focus (GtkWindow « window) 


Gets the value set by gtk_window_set_focus_on_map(). 


Parameters: 


— window a GtkWindow 


Returns: 


Retrieves the current focused widget within the window. 


6.25.2.17 gboolean gtk_window_get_focus_on_map (GtkWindow * window) 


Gets the value set by gtk_window_set_focus_on_map(). 


Parameters: 


— window a GtkWindow 


Returns: 


TRUE if window should receive the input focus when mapped. 


6.25.2.18 void gtk_window_get_frame_ dimensions (GtkWindow « window, gint x left, gint x top, 
gint x right, gint x bottom) 


(Note: this is a special-purpose function intended for the framebuffer port; see gtk_window_set_has_- 
frame(). 


It will not return the size of the window border drawn by the window manager, which is the normal case 
when using a windowing system. See gdk_window_get_frame_extents() to get the standard window border 
extents.) Retrieves the dimensions of the frame window for this toplevel. See gtk_window_set_has_- 
frame(), gtk_window_set_frame_dimensions(). 


Parameters: 
— window : a GtkWindow 
> left : location to store the width of the frame at the left, or NULL 
> top : location to store the height of the frame at the top, or NULL 
— right : location to store the width of the frame at the returns, or NULL 


> bottom : location to store the height of the frame at the bottom, or NULL 


Returns: 


void : this is a special-purpose function intended for the framebuffer port; see gtk_window_set_has_- 
frame(). It will not return the size of the window border drawn by the window manager, which is the 
normal case when using a windowing system. 
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6.25.2.19 GdkGravity gtk_window_get_gravity (GtkWindow x window) 


Gets the value set by gtk_window_set_gravity(). 


Parameters: 


— window a GtkWindow 


Returns: 


window gravity 


6.25.2.20 GtkWindowGroup« gtk_window_get_group (GtkWindow * window) 


Returns the group for window or the default group, if window is NULL or if window does not have an 
explicit window group. 


Parameters: 


+ window : a GtkWindow, or NULL 


Returns: 


the GtkWindowGroup for a window or the default group 


6.25.2.21 gboolean gtk_window_get_has_frame (GtkWindow x window) 


Accessor for whether the window has a frame window exterior to window->window. 


Gets the value set by gtk_window_set_has_frame(). 


Parameters: 


— window a GtkWindow 


Returns: 


TRUE if a frame has been added to the window via gtk_window_set_has_frame(). 


6.25.2.22  GdkPixbuf* gtk_window_get_icon (GtkWindow * window) 


Gets the value set by gtk_window_set_icon() (or if you’ve called gtk_window_set_icon_list(), gets the first 
icon in the icon list). 


Parameters: 


— window : a GtkWindow 


Returns: 


icon for window 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.25 GtkWindow 237 


6.25.2.23 GList« gtk_window_get_icon_list (GtkWindow « window) 


Retrieves the list of icons set by gtk_window_set_icon_list(). 


The list is copied, but the reference count on each member won't be incremented. 


Parameters: 


— window a GtkWindow 


Returns: 


copy of window’s icon list 


6.25.2.24 G_CONST_RETURN gchar» gtk_window_get_icon_name (GtkWindow x window) 


Returns the name of the themed icon for the window, see gtk_window_set_icon_name(). 


Parameters: 


— window a GtkWindow 


Returns: 


the icon name or NULL if the window has no themed icon 


6.25.2.25 GdkModifierType gtk_window_get_mnemonic_modifier (GtkWindow * window) 
[Deprecated] Returns the mnemonic modifier for this window. 
See gtk_window_set_mnemonic_modifier(). 


Parameters: 


< window : a GtkWindow 


Returns: 


the modifier mask used to activate mnemonics on this window. 
Deprecated 
LIMO RI 


6.25.2.26 gboolean gtk_window_get_modal (GtkWindow « window) 
Returns whether the window is modal. 
See gtk_window_set_modal(). 


Parameters: 
< window : a GtkWindow 
Returns: 


TRUE if the window is set to be modal and establishes a grab when shown 
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6.25.2.27 void gtk_window_get_position (GtkWindow « window, gint « root_x, gint x root_y) 


This function returns the position you need to pass to gtk_window_move() to keep window in its current 
position. 


This means that the meaning of the returned value varies with window gravity. See gtk_window_move() for 
more details. If you haven't changed the window gravity, its gravity will be GDK_GRAVITY_NORTH_- 
WEST. This means that gtk_window_get_position() gets the position of the top-left corner of the window 
manager frame for the window. gtk_window_move() sets the position of this same top-left corner. gtk_- 
window_get_position() is not 100% reliable because the X Window System does not specify a way to 
obtain the geometry of the decorations placed on a window by the window manager. Thus GTK+ is 
using a "best guess" that works with most window managers. Moreover, nearly all window managers are 
historically broken with respect to their handling of window gravity. So moving a window to its current 
position as returned by gtk_window_get_position() tends to result in moving the window slightly. Window 
managers are slowly getting better over time. If a window has gravity GDK_GRAVITY_STATIC the 
window manager frame is not relevant, and thus gtk_window_get_position() will always produce accurate 
results. However you can’t use static gravity to do things like place a window in a corner of the screen, 
because static gravity ignores the window manager decorations. If you are saving and restoring your 
application’s window positions, you should know that it’s impossible for applications to do this without 
getting it somewhat wrong because applications do not have sufficient knowledge of window manager 
state. The Correct Mechanism is to support the session management protocol (see the "GnomeClient" 
object in the GNOME libraries for example) and allow the window manager to save your window sizes and 
positions. 


Parameters: 


— window : a GtkWindow 
=> root_x : return location for X coordinate of gravity-determined reference p 


— root_y : return location for Y coordinate of gravity-determined reference p 


Returns: 


void 


6.25.2.28 gboolean gtk_window_get_resizable (GtkWindow x window) 
Gets the value set by gtk_window_set_resizable(). 


Parameters: 


< window a GtkWindow 


Returns: 


TRUE if the user can resize the window 


6.25.2.29 G_CONST_RETURN gchar gtk_window_get_role (GtkWindow x window) 
Returns the role of the window. 
See gtk_window_set_role() for further explanation. 


Parameters: 


< window a GtkWindow 
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Returns: 


he role of the window if set, or NULL. The returned is owned by the widget and must not be modified 
or freed. 


6.25.2.30  GdkScreen* gtk_window_get_screen (GtkWindow x window) 
Returns the GdkScreen associated with window. 


Parameters: 


— window : a GtkWindow 


Returns: 


a GdkScreen. 


6.25.2.31 void gtk_window_get_size (GtkWindow x window, gint x width, gint x height) 


Obtains the current size of window. 


If window is not onscreen, it returns the size GTK+ will suggest to the window manager for the initial 
window size (but this is not reliably the same as the size the window manager will actually select). The 
size obtained by gtk_window_get_size() is the last size received in a GdkEventConfigure, that is, GTK+ 
uses its locally-stored size, rather than querying the X server for the size. As a result, if you call gtk _- 
window_resize() then immediately call gtk_window_get_size(), the size won’t have taken effect yet. After 
the window manager processes the resize request, GTK+ receives notification that the size has changed via 
a configure event, and the size of the window gets updated. Note 1: Nearly any use of this function creates 
a race condition, because the size of the window may change between the time that you get the size and the 
time that you perform some action assuming that size is the current size. To avoid race conditions, connect 
to "configure_event" on the window and adjust your size-dependent state to match the size delivered in 
the GdkEventConfigure. Note 2: The returned size does not include the size of the window manager 
decorations (aka the window frame or border). Those are not drawn by GTK+ and GTK+ has no reliable 
method of determining their size. Note 3: If you are getting a window size in order to position the window 
onscreen, there may be a better way. The preferred way is to simply set the windows semantic type with 
gtk_window_set_type_hint(), which allows the window manager to e.g. center dialogs. Also, if you set 
the transient parent of dialogs with gtk_window_set_transient_for() window managers will often center 
the dialog over its parent window. It's much preferred to let the window manager handle these things 
rather than doing it yourself, because all apps will behave consistently and according to user prefs if the 
window manager handles it. Also, the window manager can take the size of the window decorations/border 
into account, while your application cannot. In any case, if you insist on application-specified window 
positioning, there's still a better way than doing it yourself - gtk_window_set_position() will frequently 
handle the details for you. 


Parameters: 


— window : a GtkWindow 
— width : return location for width, or NULL 


> height : return location for height, or NULL 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


240 Module Documentation 


6.25.2.32 gboolean gtk_window_get_skip_pager_hint (GtkWindow x window) 


Returns the value set by gtk_window_set_skip_pager_hint(). 


Parameters: 


— window a GtkWindow 


Returns: 


TRUE if window shouldn’t be in pager 


6.25.2.33 gboolean gtk_window_get_skip_taskbar_hint (GtkWindow * window) 


Gets the value set by gtk_window_set_skip_taskbar_hint(). 


Parameters: 


< window a GtkWindow 


Returns: 


TRUE if window shouldn’t be in taskbar 


6.25.2.34 G_CONST_RETURN gchar» gtk_window_get_title (GtkWindow « window) 


Retrieves the title of the window. 


See gtk_window_set_title(). 


Parameters: 


— window a GtkWindow 


Returns: 


the title of the window, or NULL if none has been set explicitely. The returned string is owned by the 
widget and must not be modified or freed. 


6.25.2.35 GtkWindow« gtk_window_get_transient_for (GtkWindow « window) 


Fetches the transient parent for this window. 


See gtk_window_set_transient_for(). 


Parameters: 


< window : a GtkWindow 


Returns: 


the transient parent for this window, or NULL if no transient parent has been set. 
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6.25.2.36 GdkWindowTypeHint gtk_window_get_type_hint (GtkWindow « window) 


Gets the type hint for this window. 


See gtk_window_set_type_hint(). 


Parameters: 


— window a GtkWindow 


Returns: 


the type hint for window. 


6.25.2.37 gboolean gtk_window_get_urgency_hint (GtkWindow * window) 


Gets the value set by gtk_window_set_urgency_hint(). 


Parameters: 


— window a GtkWindow 


Returns: 


TRUE if window is urgent 


6.25.2.38 void gtk_window_group_add_window (GtkWindowGroup * window_group, GtkWindow 
x window) 


Adds a window to a GtkWindowGroup. 


Parameters: 


— :aGtkWindowGroup 
+ window : the GtkWindow to add 


Returns: 


void 


6.25.2.39 GType gtk_window_group_get_type (void) 


Window group type. 


6.25.2.40 GtkWindowGroup* gtk_window_group_new (void) 


Creates new window group. 


Returns: 


new window group 
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6.25.2.41 void gtk_window_group_remove_window (GtkWindowGroup * window_group, 
GtkWindow « window) 


Removes a window from GtkWindowGroup. 


Parameters: 
— window_group : a GtkWindowGroup 


— window : the GtkWindow to remove 


Returns: 


void 


6.25.2.42  gboolean gtk_window_has_toplevel_focus (GtkWindow « window) 


Returns whether the input focus is within this GtkWindow. 

For real toplevel windows, this is identical to gtk_window_is_active(), but for embedded windows, like 
GtkPlug, the results will differ. 

Parameters: 


— window a GtkWindow 


Returns: 


TRUE if the input focus is within this GtkWindow 


6.25.2.43 void gtk_window_iconify (GtkWindow x window) 


[Deprecated] Asks to iconify (that is minimize) the specified window. 


Note that you shouldn’t assume the window is definitely iconified afterward, because other entities (e.g. 
the user or window manager) could deiconify it again, or there may not be a window manager in which 
case iconification isn’t possible, etc. But normally the window will end up iconified. Just don’t write code 
that crashes if not. It’s permitted to call this function before showing a window, in which case the window 
will be iconified before it ever appears onscreen. You can track iconification via the "window_state_event" 
signal on GtkWidget. 

Parameters: 


< window a GtkWindow 


Returns: 


void 


Deprecated 
LIMO R1 
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6.25.2.44 gboolean gtk_window_is_active (GtkWindow x window) 


Returns whether the window is part of the current active toplevel. 


The return value is TRUE if the window is active toplevel itself, but also if it is, say, a GtkPlug embedded 
in the active toplevel. You might use this function 1f you wanted to draw a widget differently in an active 
window from a widget in an inactive window. See gtk_window_has_toplevel_focus() 


Parameters: 


— window a GtkWindow 


Returns: 


TRUE if the window part of the current active window. 


6.25.2.45 gboolean gtk_window_is_bg_transparent (GtkWindow x window) 
Returns whether the Window is Transparent or Opaque to its parant. 


Parameters: 


window [in] a GtkWindow 


Returns: 
Transparent or Not.] TRUE means, window will be rendered transparently on its Parant. FALSE means 
Window is Opaque, and its exposed area of parant will be cleard out by the window. 

Since 


LIMO R1 


6.25.2.46 GListx gtk_window_list_toplevels (void) 


Returns a list of all existing toplevel windows. 


The widgets in the list are not individually referenced. If you want to iterate through the list and perform 
actions involving callbacks that might destroy the widgets, you must call g_list_foreach (result, (GFunc)g_- 
object_ref, NULL) first, and then unref all the widgets afterwards. 


Returns: 


list of toplevel widgets 


6.25.2.47 void gtk_window_maximize (GtkWindow x window) 


Asks to maximize window, so that it becomes full-screen. 


Note that you shouldn’t assume the window is definitely maximized afterward, because other entities (e.g. 
the user or window manager) could unmaximize it again, and not all window managers support maximiza- 
tion. But normally the window will end up maximized. Just don’t write code that crashes if not. It’s 
permitted to call this function before showing a window, in which case the window will be maximized 
when it appears onscreen initially. You can track maximization via the "window_state_event" signal on 
GtkWidget. 
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Parameters: 


— window a GtkWindow 


Returns: 


void 


6.25.2.48  gboolean gtk_window_mnemonic_activate (GtkWindow * window, guint keyval, 
GdkModifierType modifier) 


[Deprecated] Activates the targets associated with the mnemonic. 


Parameters: 


< window : a GtkWindow 
— keyval : the mnemonic 


— keyval : the mnemonic 


Returns: 


TRUE if the activation is done. 


Deprecated 
LIMO R1 


6.25.2.49 void gtk_window_move (GtkWindow x window, gint x, gint y) 


Asks the window manager to move window to the given position. 


Window managers are free to ignore this; most window managers ignore requests for initial window po- 
sitions (instead using a user-defined placement algorithm) and honor requests after the window has al- 
ready been shown. Note: the position is the position of the gravity-determined reference point for the 
window. The gravity determines two things: first, the location of the reference point in root window co- 
ordinates; and second, which point on the window is positioned at the reference point. By default the 
gravity is GDK_GRAVITY_NORTH_WEST, so the reference point is simply the x, y supplied to gtk_- 
window_move(). The top-left corner of the window decorations (aka window frame or border) will be 
placed at x, y. Therefore, to position a window at the top left of the screen, you want to use the de- 
fault gravity (which is GDK_GRAVITY_NORTH_WEST) and move the window to 0,0. To position a 
window at the bottom right corner of the screen, you would set GDK_GRAVITY_SOUTH_EAST, which 
means that the reference point is at x + the window width and y + the window height, and the bottom- 
right corner of the window border will be placed at that reference point. So, to place a window in 
the bottom right corner you would first set gravity to south east, then write: gtk_window_move (win- 
dow, gdk_screen_width() - window_width, gdk_screen_height() - window_height) (note that this example 
does not take multi-head scenarios into account). The Extended Window Manager Hints specification 
athttp:////www.freedesktop.org/Standards/wm-spec has a nice table of gravities in the 
"implementation notes" section. The gtk_window_get_position() documentation may also be relevant. 


Parameters: 


— window : a GtkWindow 


+ x : X coordinate to move window to 
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— y : Y coordinate to move window to 


Returns: 


void 


6.25.2.50 GtkWidget« gtk_window_new (GtkWindowType type) 


Creates a new GtkWindow, which is a toplevel window that can contain other widgets. 


Nearly always, the type of the window should be GTK_WINDOW_TOPLEVEL. If you're implementing 
something like a popup menu from scratch (which is a bad idea, just use GtkMenu), you might use GTK_- 
WINDOW_POPUP. GTK_WINDOW_POPUP is not for dialogs, though in some other toolkits dialogs 
are called "popups". If you simply want an undecorated window (no window borders), use gtk_window_- 
set_decorated(), don’t use GTK_WINDOW_POPUP. In GTK+, GTK_WINDOW_POPUP means a pop-up 
menu or pop-up tooltip. On X11, popup windows are not controlled by the window manager. 


Parameters: 


< type type of window 


Returns: 


anew GtkWindow. 


6.25.2.51 gboolean gtk_window_parse_geometry (GtkWindow * window, const gchar « geometry) 


Parses a standard X Window System geometry string - see the manual page for X (type "man X’) for details 
on this. 


gtk_window_parse_geometry() does work on all GTK+ ports including Win32 but is primarily intended 
for an X environment. If either a size or a position can be extracted from the geometry string, gtk_- 
window_parse_geometry() returns TRUE and calls gtk_window_set_default_size() and/or gtk_window_- 
move() to resize/move the window. If gtk_window_parse_geometry() returns TRUE, it will also set the 
GDK_HINT_USER_POS and/or GDK_HINT_USER_SIZE hints indicating to the window manager that 
the size/position of the window was user-specified. This causes most window managers to honor the 
geometry. Note that for gtk_window_parse_geometry() to work as expected, it has to be called when the 
window has its "final" size, i.e. after calling gtk_widget_show_all() on the contents and gtk_window_set_- 
geometry_hints() on the window. 


include <gtk/gtk.h> 


static void 
fill_with_content (GtkWidget x*vbox) 
{ 
// fi11 with content... 
} 


int 
main (int argc, char xargv[]) 
{ 
GtkWidget «window, *vbox; 
GdkGeometry size_hints = { 
100, 50, 0, 0, 100, 50, 10, 10, 0.0, 0.0, GDK_GRAVITY_NORTH_WEST 
y; 
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gtk_init (&argc, &argv); 


window = gtk_window_new (GTK_WINDOW_TOPLEVEL) ; 
vbox = gtk_vbox_new (FALSE, 0); 


gtk_container_add (GTK_CONTAINER (window), vbox); 
fill_with_content (vbox); 
gtk_widget_show_all (vbox); 


gtk_window_set_geometry_hints (GTK_WINDOW (window), 
window, 
&size_hints, 
GDK_HINT_MIN_SIZE | 
GDK_HINT_BASE_SIZE | 
GDK_HINT_RESIZE_INC) ; 


if {arge > 1) 
{ 

if (!gtk_window_parse_geometry (GTK_WINDOW (window), argv[1])) 

fprintf (stderr, "Failed to parse ’%s’\n", argv[1]); 


} 


gtk_widget_show_all (window) ; 
gtk_main(); 


return 0; 


} 


Parameters: 


< window : a GtkWindow 
— geometry : geometry string 


Returns: 


Returns : TRUE if string was parsed successfully 


6.25.2.52 void gtk_window_present (GtkWindow * window) 


Presents a window to the user. 


This may mean raising the window in the stacking order, deiconifying it, moving it to the current desktop, 
and/or giving it the keyboard focus, possibly dependent on the user’s platform, window manager, and 
preferences. If window is hidden, this function calls gtk_widget_show() as well. This function should be 
used when the user tries to open a window that’s already open. Say for example the preferences dialog is 
currently open, and the user chooses Preferences from the menu a second time; use gtk_window_present() 
to move the already-open dialog where the user can see it. If you are calling this function in response to a 


user interaction, it is preferable to use gtk_window_present_with_time(). 


Parameters: 
— window a GtkWindow 


Returns: 


void 


6.25.2.53 void gtk_window_present_with_time (GtkWindow x window, guint32 timestamp) 


Presents a window to the user in response to a user interaction. 
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If you need to present a window without a timestamp, use gtk_window_present() for details. 


Parameters: 


< window : a GtkWindow 


< timestamp : the timestamp of the user interaction (typically a button or key press event) which 
triggered this call 
Returns: 


void 


6.25.2.54 gboolean gtk_window_propagate_key_event (GtkWindow x window, GdkEventKey = 
event) 


Propagate a key press or release event to the focus widget and up the focus container chain until a widget 
handles event. 


This is normally called by the default key_press_event and key_release_event handlers for toplevel win- 
dows, however in some cases it may be useful to call this directly when overriding the standard key handling 
for a toplevel window. 


Parameters: 


< window : a GtkWindow 


— event : a GdkEventKey 


Returns: 


TRUE if a widget in the focus chain handled the event. 


6.25.2.55 void gtk_window_remove_accel_group (GtkWindow * window, GtkAccelGroup = 
accel_group) 


Reverses the effects of gtk_window_add_accel_group(). 


Parameters: 


— window : a GtkWindow 


— accel_group : a GtkAccelGroup 


Returns: 


void 


6.25.2.56 void gtk_window_remove_mnemonic (GtkWindow x window, guint keyval, Gtk Widget x 
target) 


[Deprecated] Removes a mnemonic from this window. 


Parameters: 


— window : a GtkWindow 
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— keyval : the mnemonic 


— target : the widget that gets activated by the mnemonic 


Returns: 


void 


Deprecated 
LIMO R1 


6.25.2.57 void gtk_window_reshow_with_initial_size (GtkWindow * window) 


Hides window, then reshows it, resetting the default size and position of the window. 


Used by GUI builders only. 


Parameters: 


— window : a GtkWindow 


Returns: 


void 


Remarks: 


Ignore this unless you are writing a GUI builder 


6.25.2.58 void gtk_window_resize (Gtk Window « window, gint width, gint height) 


Resizes the window as if the user had done so, obeying geometry constraints.The default geometry con- 
straint is that windows may not be smaller than their size request; to override this constraint, call gtk_- 
widget_set_size_request() to set the window’s request to a smaller value. 


If gtk_window_resize() is called before showing a window for the first time, it overrides any default size 
set with gtk_window_set_default_size(). Windows may not be resized smaller than 1 by 1 pixels. 


Parameters: 


— window : a GtkWindow 
— width : width in pixels to resize the window to 


— height : height in pixels to resize the window to 


Returns: 


void 


6.25.2.59 void gtk_window_set_accept_focus (GtkWindow * window, gboolean setting) 


Windows may set a hint asking the desktop environment not to receive the input focus. 


This function sets this hint. 
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Parameters: 


— window : a GtkWindow 


— setting : TRUE to let this window receive input focus 


Returns: 


void 


6.25.2.60 void gtk_window_set_auto_startup_notification (gboolean setting) 


By default, after showing the first GtkWindow, GTK+ calls gdk_notify_startup_complete(). 


Call this function to disable the automatic startup notification. You might do this if your first window is 
a splash screen, and you want to delay notification until after your real main window has been shown, for 
example. In that example, you would disable startup notification temporarily, show your splash screen, 
then re-enable it so that showing the main window would automatically result in notification. 


Parameters: 


— setting : TRUE to automatically do startup notification 


Returns: 


void 


6.25.2.61 void gtk_window_set_bg_transparent (GtkWindow x window, gboolean transparent) 


Sets the window background as transparent. 

This window will not clearout its parents data. Window will be drawn on top its Parent without clearing 
the Parent rendering data. 

Parameters: 


window [in] a GtkWindow 


transparent [in] TRUE means, window will be rendered transparently on its Parant. FALSE means 
Window is Opaque, and its exposed area of parant will be cleard out by the window. 
Returns: 


void 


Since 


LIMO R1 


6.25.2.62 void gtk_window_set_decorated (GtkWindow x window, gboolean setting) 
This function is used to set the decoration property of the window.By default, windows are decorated with 
a title bar, resize controls, etc. 


Some window managers allow GTK+ to disable these decorations, creating a borderless window. If you 
set the decorated property to FALSE using this function, GTK+ will do its best to convince the window 
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manager not to decorate the window. Depending on the system, this function may not have any effect when 
called on a window that is already visible, so you should call it before calling gtk_window_show(). On 
Windows, this function always works, since there’s no window manager policy involved. 


Parameters: 


< window : a GtkWindow 


— setting : TRUE to decorate the window 


Returns: 


void 


6.25.2.63 void gtk_window_set_default (GtkWindow x window, GtkWidget x default_widget) 


This function sets or unsets the default widget for a Gtk Window about. 


When setting (rather than unsetting) the default widget it’s generally easier to call gtk_widget_grab_focus() 
on the widget. Before making a widget the default widget, you must set the GTK_CAN_DEFAULT flag 
on the widget you'd like to make the default using GTK_WIDGET_SET_FLAGS(). 


Parameters: 


— window : a GtkWindow 
— default_widget : widget to be the default, or NULL to unset the default widget for the toplevel. 


Returns: 


void 


6.25.2.64 void gtk_window_set_default_icon (GdkPixbuf « icon) 


Sets an icon to be used as fallback for windows that haven’t had gtk_window_set_icon() called on them 
from a pixbuf. 


Parameters: 


< icon : the icon 


Returns: 


void 


6.25.2.65 gboolean gtk_window_set_default_icon_from_file (const gchar x filename, GError «x 
err) 


Sets an icon to be used as fallback for windows that haven’t had gtk_window_set_icon_list() called on 
them from a file on disk. 


Warns on failure if err is NULL. 


Parameters: 


+— filename : location of icon file 
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— err : location to store error, or NULL. 


Returns: 


TRUE if setting the icon succeeded. 


6.25.2.66 void gtk_window_set_default_icon_list (GList + list) 


Sets an icon list to be used as fallback for windows that haven't had gtk_window_set_icon_list() called on 
them to set up a window-specific icon list. 


This function allows you to set up the icon for all windows in your app at once. See gtk_window_set_- 
icon_list() for more details. 


Parameters: 


— list : a list of GdkPixbuf 


Returns: 


void 


6.25.2.67 void gtk_window_set_default_icon_name (const gchar * name) 


Sets an icon to be used as fallback for windows that haven’t had gtk_window_set_icon_list() called on 
them from a named themed icon, see gtk_window_set_icon_name(). 


Parameters: 


< name : the name of the themed icon 


Returns: 


void 


6.25.2.68 void gtk_window_set_default_size (GtkWindow x window, gint width, gint height) 


Sets the default size of a window. 


If the window’s "natural" size (its size request) is larger than the default, the default will be ignored. More 
generally, if the default size does not obey the geometry hints for the window (gtk_window_set_geometry_- 
hints() can be used to set these explicitly), the default size will be clamped to the nearest permitted size. 
Unlike gtk_widget_set_size_request(), which sets a size request for a widget and thus would keep users 
from shrinking the window, this function only sets the initial size, just as if the user had resized the window 
themselves. Users can still shrink the window again as they normally would. Setting a default size of -1 
means to use the "natural" default size (the size request of the window). For more control over a window’s 
initial size and how resizing works, investigate gtk_window_set_geometry_hints(). For some uses, gtk_- 
window_resize() is a more appropriate function. gtk_window_resize() changes the current size of the 
window, rather than the size to be used on initial display. gtk_window_resize() always affects the window 
itself, not the geometry widget. The default size of a window only affects the first time a window is shown; 
if a window is hidden and re-shown, it will remember the size it had prior to hiding, rather than using the 
default size. Windows can’t actually be 0x0 in size, they must be at least 1x1, but passing 0 for width and 
height is OK, resulting in a 1x1 default size. 
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Parameters: 
— window : a GtkWindow 
— width : width in pixels, or -1 to unset the default width 


— height : height in pixels, or -1 to unset the default height 


Returns: 


void 


6.25.2.69 void gtk_window_set_deletable (GtkWindow « window, gboolean setting) 


By default, windows have a close button in the window frame. 


Some window managers allow GTK+ to disable this button. If you set the deletable property to FALSE 
using this function, GTK+ will do its best to convince the window manager not to show a close button. 
Depending on the system, this function may not have any effect when called on a window that is already 
visible, so you should call it before calling gtk_window_show(). On Windows, this function always works, 
since there’s no window manager policy involved. 
Parameters: 

— window : a GtkWindow 


— setting : TRUE to decorate the window as deletable 


Returns: 


void 


6.25.2.70 void gtk_window_set_destroy_with_parent (GtkWindow « window, gboolean setting) 


Tf setting is TRUE, then destroying the transient parent of window will also destroy window itself. 
This is useful for dialogs that shouldn’t persist beyond the lifetime of the main window they're associated 
with, for example. 
Parameters: 
— window : a GtkWindow 


— setting : whether to destroy window with its transient parent 


Returns: 


void 


6.25.2.71 void gtk_window_set_focus (GtkWindow « window, GtkWidget x focus) 


If focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. 


If focus is NULL, unsets the focus widget for this window. To set the focus to a particular widget in the 
toplevel, it is usually more convenient to use gtk_widget_grab_focus() instead of this function. 
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Parameters: 
— window a GtkWindow 
— focus : widget to be the new focus widget, or NULL to unset any focus widget for the toplevel 
window. 
Returns: 


void 


6.25.2.72 void gtk_window_set_focus_on_map (GtkWindow x window, gboolean setting) 


Windows may set a hint asking the desktop environment not to receive the input focus when the window is 
mapped. 


This function sets this hint. 


Parameters: 
— window : a GtkWindow 


< : TRUE to let this window receive input focus on map 


Returns: 


void 


6.25.2.73 void gtk_window_set_frame_dimensions (GtkWindow « window, gint left, gint top, gint 
right, gint bottom) 


(Note: this is a special-purpose function intended for the framebuffer port; see gtk_window_set_has_- 
frame(). 


It will have no effect on the window border drawn by the window manager, which is the normal case when 
using the X Window system.) For windows with frames (see gtk_window_set_has_frame()) this function 
can be used to change the size of the frame border. 


Parameters: 
— window : a GtkWindow that has a frame 
— left : The width of the left border 
— top : The height of the top border 
— right : The width of the right border 


— bottom : The height of the bottom border 


Returns: 


void : this is a special-purpose function intended for the framebuffer port; see gtk_window_set_has_- 
frame(). It will have no effect on the window border drawn by the window manager, which is the 
normal case when using the X Window system. 
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6.25.2.74 void gtk_window_set_geometry_hints (GtkWindow * window, GtkWidget x 
geometry_widget, GdkGeometry x geometry, GdkWindowHints geom_mask) 

This function sets up hints about how a window can be resized by the user. 

You can set a minimum and maximum size; allowed resize increments (e.g. for xterm, you can only resize 

by the size of a character); aspect ratios; and more. See the GdkGeometry struct. 

Parameters: 


— wiwindow : a GtkWindow 
— geometry_widget : widget the geometry hints will be applied to 
— geometry : struct containing geometry information 


— geom_mask : mask indicating which struct fields should be paid attention to 


Returns: 


void 


6.25.2.75 void gtk_window_set_gravity (GtkWindow * window, GdkGravity gravity) 


Window gravity defines the meaning of coordinates passed to gtk_window_move(). 
See gtk_window_move() and GdkGravity for more details. The default window gravity is GDK_- 
GRAVITY_NORTH_WEST which will typically "do what you mean." 
Parameters: 
— window : a GtkWindow 


— gravity : window gravity 


Returns: 


void 


6.25.2.76 void gtk_window_set_has_frame (GtkWindow « window, gboolean setting) 
If this function is called on a window with setting of TRUE, before it is realized or showed, it will have a 
"frame" window around window->window, accessible in window->frame. 


Using the signal frame_event you can receive all events targeted at the frame. This function is used by the 
linux-fb port to implement managed windows, but it could conceivably be used by X-programs that want 
to do their own window decorations. 


Parameters: 
< window : a GtkWindow 


< setting : a boolean 


Returns: 


void gtk_window_set_has_frame () must be called before realizing the window_ 
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6.25.2.77 void gtk_window_set_icon (GtkWindow * window, GdkPixbuf x icon) 


Sets up the icon representing a GtkWindow. 


This icon is used when the window is minimized (also known as iconified). Some window managers or 
desktop environments may also place it in the window frame, or display it in other contexts. The icon 
should be provided in whatever size it was naturally drawn; that is, don’t scale the image before passing 
it to GTK+. Scaling is postponed until the last minute, when the desired final size is known, to allow best 
quality. If you have your icon hand-drawn in multiple sizes, use gtk_window_set_icon_list(). Then the 
best size will be used. This function is equivalent to calling gtk_window_set_icon_list() with a 1-element 
list. See also gtk_window_set_default_icon_list() to set the icon for all windows in your application in one 


go. 


Parameters: 

— window : a GtkWindow 

< icon : icon image, or NULL 
Returns: 


void 


6.25.2.78 gboolean gtk_window_set_icon_from_file (GtkWindow « window, const gchar + filename, 
GError xx err) 


Sets the icon for window. 


Warns on failure if err is NULL. This function is equivalent to calling gtk_window_set_icon() with a pixbuf 
created by loading the image from filename. 


Parameters: 


— window : a GtkWindow 
— filename : location of icon file 


=> err : location to store error, or NULL. 


Returns: 


TRUE if setting the icon succeeded. 


6.25.2.79 void gtk_window_set_icon_list (Gtk Window x window, GList x list) 


Sets up the icon representing a Gtk Window. 


The icon is used when the window is minimized (also known as iconified). Some window managers or 
desktop environments may also place it in the window frame, or display it in other contexts. gtk_window_- 
set_icon_list() allows you to pass in the same icon in several hand-drawn sizes. The list should contain the 
natural sizes your icon is available in; that is, don’t scale the image before passing it to GTK+. Scaling 
is postponed until the last minute, when the desired final size is known, to allow best quality. By passing 
several sizes, you may improve the final image quality of the icon, by reducing or eliminating automatic 
image scaling. Recommended sizes to provide: 16x16, 32x32, 48x48 at minimum, and larger images 
(64x64, 128x128) if you have them. See also gtk_window_set_default_icon_list() to set the icon for all 
windows in your application in one go. Note that transient windows (those who have been set transient for 
another window using gtk_window_set_transient_for()) will inherit their icon from their transient parent. 
So there’s no need to explicitly set the icon on transient windows. 
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Parameters: 


— window : a GtkWindow 
— list : list of GdkPixbuf 


Returns: 


void 


6.25.2.80 void gtk_window_set_icon_name (GtkWindow * window, const gchar x name) 


Sets the icon for the window from a named themed icon. 


See the docs for GtkIconTheme for more details Note that this has nothing to do with the WM_ICON_- 
NAME property which is mentioned in the ICCCM. 


Parameters: 


— window : a GtkWindow 


< name : the name of the themed icon 


Returns: 


void 


6.25.2.81 void gtk_window_set_keep_above (GtkWindow « window, gboolean setting) 


Asks to keep window above, so that it stays on top. 


Note that you shouldn’t assume the window is definitely above afterward, because other entities (e.g. the 
user or window manager) could not keep it above, and not all window managers support keeping windows 
above. But normally the window will end kept above. Just don’t write code that crashes if not. You can 
track the fullscreen state via the "window_state_event" signal on GtkWidget. It’s permitted to call this 
function before showing a window, in which case the window will be kept above when it appears onscreen 
initially. You can track the above state via the "window_state_event" signal on GtkWidget. Note that, 
according to the Extended Window Manager Hints specification, the above state is mainly meant for user 
preferences and should not be used by applications e.g. for drawing attention to their dialogs. 


Parameters: 


< window : a GtkWindow 


— setting : whether to keep window above other windows 


Returns: 


void 


6.25.2.82 void gtk_window_set_keep_below (GtkWindow « window, gboolean setting) 


Asks to keep window below, so that it stays in bottom. 


Note that you shouldn’t assume the window is definitely below afterward, because other entities (e.g. the 
user or window manager) could not keep it below, and not all window managers support putting windows 
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below. But normally the window will be kept below. Just don’t write code that crashes if not. It’s permitted 
to call this function before showing a window, in which case the window will be kept below when it appears 
onscreen initially. You can track the below state via the "window_state_event" signal on GtkWidget. Note 
that, according to the Extended Window Manager Hints specification, the above state is mainly meant for 
user preferences and should not be used by applications e.g. for drawing attention to their dialogs. 
Parameters: 


— window : a GtkWindow 


— setting : whether to keep window below other windows 


Returns: 


void 


6.25.2.83 void gtk_window_set_mnemonic_modifier (GtkWindow * window, GdkModifierType 
modifier) 


[Deprecated] Sets the mnemonic modifier for this window. 


Parameters: 


— window : a GtkWindow 


— modifier : the modifier mask used to activate mnemonics on this window. 


Returns: 


void 
Deprecated 
LIMO R1 


6.25.2.84 void gtk_window_set_modal (GtkWindow * window, gboolean modal) 


Sets a window modal or non-modal. 


Modal windows prevent interaction with other windows in the same application. To keep modal dialogs on 
top of main application windows, use gtk_window_set_transient_for() to make the dialog transient for the 
parent; most window managers will then disallow lowering the dialog below the parent. 


Parameters: 


< window : a GtkWindow 


< modal : whether the window is modal 


Returns: 


void 


Remarks: 


If window is set modal, input will be grabbed when show and released when hide 
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6.25.2.85 void gtk_window_set_position (GtkWindow x window, GtkWindowPosition position) 


Sets a position constraint for this window. 
If the old or new constraint is GTK_WIN_POS_CENTER_ALWAYS, this will also cause the window to 
be repositioned to satisfy the new constraint. 
Parameters: 
— window : a GtkWindow. 


— position : a position constraint. 


Returns: 


void 


6.25.2.86 void gtk_window_set_resizable (Gtk Window « window, gboolean resizable) 


Sets whether the user can resize a window. 


Windows are user resizable by default. 


Parameters: 
— window : a GtkWindow 


— resizable : TRUE if the user can resize this window 


Returns: 


void 


6.25.2.87 void gtk_window_set_role (GtkWindow « window, const gchar x role) 


This function is only useful on X11, not with other GTK+ targets. 


In combination with the window title, the window role allows a window manager to identify "the same" 
window when an application is restarted. So for example you might set the "toolbox" role on your app’s 
toolbox window, so that when the user restarts their session, the window manager can put the toolbox back 
in the same place. If a window already has a unique title, you don’t need to set the role, since the WM can 
use the title to identify the window when restoring the session. 


Parameters: 
< window a GtkWindow 


— role unique identifier for the window to be used when restoring a session 


Returns: 


void 
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6.25.2.88 void gtk_window_set_screen (GtkWindow * window, GdkScreen « screen) 


Sets the GdkScreen where the window is displayed; if the window is already mapped, it will be unmapped, 
and then remapped on the new screen. 


Parameters: 


< window : a GtkWindow 


< screen : a GdkScreen. 


Returns: 


void 


6.25.2.89 void gtk_window_set_skip_pager_hint (GtkWindow x window, gboolean setting) 


Windows may set a hint asking the desktop environment not to display the window in the pager. 


This function sets this hint. (A "pager" is any desktop navigation tool such as a workspace switcher that 
displays a thumbnail representation of the windows on the screen.) 


Parameters: 


< window : a GtkWindow 


< setting : TRUE to keep this window from appearing in the pager 


Returns: 


void 


6.25.2.90 void gtk_window_set_skip_taskbar_hint (GtkWindow « window, gboolean setting) 


Windows may set a hint asking the desktop environment not to display the window in the task bar. 


This function sets this hint. 


Parameters: 


< window : a GtkWindow 


< setting : TRUE to keep this window from appearing in the task bar 


Returns: 


void 


6.25.2.91 void gtk_window_set_title (GtkWindow x window, const gchar + title) 


Sets the title of the GtkWindow. 


The title of a window will be displayed in its title bar; on the X Window System, the title bar is rendered 
by the window manager, so exactly how the title appears to users may vary according to a user’s exact 
configuration. The title should help a user distinguish this window from other windows they may have 
open. A good title might include the application name and current document filename, for example. 
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Parameters: 


— window a GtkWindow 


— title title of the window 


Returns: 


void 


6.25.2.92 void gtk_window_set_transient_for (GtkWindow * window, GtkWindow = parent) 


Dialog windows should be set transient for the main application window they were spawned from. 


This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog 
over the main window. gtk dialog new_with_buttons() and other convenience functions in GTK+ will 
sometimes call gtk_window_set_transient_for() on your behalf. On Windows, this function will and put 
the child window on top of the parent, much as the window manager would have done on X 


Parameters: 
< window : a GtkWindow 


— parent : parent window 


Returns: 


void 


6.25.2.93 void gtk_window_set_type_hint (GtkWindow « window, GdkWindowTypeHint hint) 


This function sets the type hint for the window, So, you allow the window manager to decorate and handle 
the window in a way which is suitable to the function of the window in your application. 


This function should be called before the window becomes visible. gtk_dialog_new_with_buttons() and 
other convenience functions in GTK+ will sometimes call gtk_window_set_type_hint() on your behalf. 


Parameters: 


< window : a GtkWindow 


— hint : the window type 


Returns: 


void 


6.25.2.94 void gtk_window_set_urgency_hint (GtkWindow x window, gboolean setting) 
Windows may set a hint asking the desktop environment to draw the users attention to the window. 
This function sets this hint. 


Parameters: 


— window : a GtkWindow 
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— setting : TRUE to mark this window as urgent 


Returns: 


void 


6.25.2.95 void gtk_window_set_wmclass (Gtk Window * window, const gchar * wmclass_name, 
const gchar * wmclass_class) 
Don’t use this function. 


It sets the X Window System "class" and "name" hints for a window. According to the ICCCM, you should 
always set these to the same value for all windows in an application, and GTK+ sets them to that value by 
default, so calling this function is sort of pointless. However, you may want to call gtk_window_set_role() 
on each window in your application, for the benefit of the session manager. Setting the role allows the 
window manager to restore window positions when loading a saved session. 


Parameters: 


— window a GtkWindow 
— wmclass_name window name hint 


< wmeclass_class window class hint 


Returns: 


void 


6.25.2.96 void gtk_window_stick (GtkWindow « window) 


Asks to stick window, which means that it will appear on all user desktops. 


Note that you shouldn’t assume the window is definitely stuck afterward, because other entities (e.g. the 
user or window manager) could unstick it again, and some window managers do not support sticking 
windows. But normally the window will end up stuck. Just don’t write code that crashes if not. It’s 
permitted to call this function before showing a window. You can track stickiness via the "window_state_- 
event" signal on Gtk Widget. 


Parameters: 


< window a GtkWindow 


Returns: 


void 


6.25.2.97 void gtk_window_unfullscreen (GtkWindow * window) 


Asks to toggle off the fullscreen state for window. 


Note that you shouldn’t assume the window is definitely not full screen afterward, because other entities 
(e.g. the user or window manager) could fullscreen it again, and not all window managers honor requests 
to unfullscreen windows. But normally the window will end up restored to its normal state. Just don’t 
write code that crashes if not. You can track the fullscreen state via the "window_state_event" signal on 
GtkWidget. 
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Parameters: 


— window a GtkWindow 


Returns: 


void 


6.25.2.98 void gtk_window_unmaximize (GtkWindow x window) 


Asks to unmaximize window. 


Note that you shouldn’t assume the window is definitely unmaximized afterward, because other entities 
(e.g. the user or window manager) could maximize it again, and not all window managers honor requests 
to unmaximize. But normally the window will end up unmaximized. Just don't write code that crashes if 
not. 


Parameters: 


— window a GtkWindow 


Returns: 


void 


6.25.2.99 void gtk_window_unstick (GtkWindow « window) 


Asks to unstick window, which means that it will appear on only one of the user's desktops. 


Note that you shouldn’t assume the window is definitely unstuck afterward, because other entities could 
stick it again. But normally the window will end up stuck. Just don’t write code that crashes if not. You 
can track stickiness via the "window_state_event" signal on GtkWidget. 


Parameters: 


< window a GtkWindow 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.26 Display Widgets 263 


6.26 Display Widgets 


Modules 


e GtkImage 
The GtkImage widget displays an image. 


e GtkLabel 
The GtkLabel widget displays a small amount of text. 


e GtkProgressBar 


GtkProgressBar is a widget which indicates progress visually. 
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6.27 GtkImage 


6.27.1 Detailed Description 


The GtkImage widget displays an image. 


Various kinds of object can be displayed as an image; most typically, you would load a GdkPixbuf ("pixel 
buffer") from a file, and then display that. There’s a convenience function to do this, gtk_image_new_- 
from_file(), used as follows: 


Figure 6.3: GtkImage 


GtkWidget «image; 


image = gtk_image_new_from_file ("myfile.png"); 


If the file isn’t loaded successfully, the image will contain a "broken image" icon similar to that used in 
many web browsers. If you want to handle errors in loading the file yourself, for example by displaying 
an error message, then load the image with gdk_pixbuf_new_from_file(), then create the GtkImage with 
gtk_image_new_from_pixbuf(). 


The image file may contain an animation, if so the GtkImage will display an animation (GdkPixbufAnima- 
tion) instead of a static image. 


GtkImage is a subclass of GtkMisc, which implies that you can align it (center, left, right) and add padding 
to it, using GtkMisc methods. 


GtkImage is a "no window" widget (has no Gdk Window of its own), so by default does not receive events. 
If you want to receive events on the image, such as button clicks, place the image inside a GtkEventBox, 
then connect to the event signals on the event box. 


Code Example 


static gboolean 


button_press_callback (GtkWidget xevent_box, 
GdkEventButton x*event, 
gpointer data) 


{ 
g_print ("Event box clicked at coordinates %f,%f\n", 
event->x, event->y); 


// Returning TRUE means we handled the event, so the signal 
// emission should be stopped (don’t call any further 

// callbacks that may be connected). Return FALSE 

// to continue invoking callbacks. 


return TRUE; 
} 


static GtkWidget 
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create_image (void) 

{ 
GtkWidget ximage; 
GtkWidget *event_box; 


image = gtk_image_new_from_file ("myfile.png"); 


event_box = gtk_event_box_new (); 
gtk_container_add (GTK_CONTAINER (event_box), image); 


g_signal_connect (G_OBJECT (event_box), 
"button_press_event", 
G_CALLBACK (button_press_callbacx), 
image); 


return image; 


When handling events on the event box, keep in mind that coordinates in the image may be different from 
event box coordinates due to the alignment and padding settings on the image (see GtkMisc). The simplest 
way to solve this is to set the alignment to 0.0 (left/top), and set the padding to zero. Then the origin of 
the image will be the same as the origin of the event box. Sometimes an application will want to avoid 
depending on external data files, such as image files. GTK+ comes with a program to avoid this, called 
gdk-pixbuf-csource. This program allows you to convert an image into a C variable declaration, which can 
then be loaded into a GdkPixbuf using gdk_pixbuf_new_from_inline(). 


Data Structures 


e struct _GtkImagePixmapData 


GtkImagePixmapData instance structure. 


e struct _GtkImageImageData 


GtklImagelmageData instance structure. 


e struct _GtkImagePixbufData 


GtkImagePixbufData instance structure. 


e struct _GtkImageStockData 


GtkImageStockData instance structure. 


e struct _GtkImagelconSetData 


GtkImagelconSetData instance structure. 


e struct _GtkImageAnimationData 


GtkImageAnimationData instance structure. 


e struct _GtkImageIconNameData 


GtklImagelconNameData instance structure. 


e struct _GtkImage 


GtkImage instance structure. 


e struct _GtkImageClass 


GtkImage instance class structure. 
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Functions 


e GtkWidget * gtk_image_new (void) 


Creates a new empty GtkImage widget. 


e GtkWidget * gtk_image_new_from_pixmap (GdkPixmap *pixmap, GdkBitmap *mask) 


Creates a GtkImage widget displaying pixmap with a mask. 


e GtkWidget * gtk_image_new_from_image (GdkImage *image, GdkBitmap *mask) 


Creates a GtkImage widget displaying a image with a mask. 


e GtkWidget * gtk_image_new_from_file (const gchar +filename) 


Creates a new GtkImage displaying the file filename. 


e GtkWidget x gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf) 


Creates a new GtkImage displaying pixbuf. 


e GtkWidget * gtk_image_new_from_stock (const gchar *stock_id, GtkIconSize size) 


Creates a GtkIlmage displaying a stock icon. 


e GtkWidget * gtk_image_new_from_icon_set (GtkIconSet *icon_set, GtkIconSize size) 


Creates a GtkImage displaying an icon set. 


e GtkWidget x gtk_image_new_from_animation (GdkPixbufAnimation *animation) 


Creates a GtkImage displaying the given animation. 


e GtkWidget x gtk_image_new_from_icon_name (const gchar *icon_name, GtkIconSize size) 


Creates a GtkImage displaying an icon from the current icon theme. 


e void gtk_image_clear (GtkImage *image) 


Resets the image to be empty. 


e void gtk_image_set_from_pixmap (GtkImage *image, GdkPixmap *pixmap, GdkBitmap *mask) 


Sets a GtkImage widget displaying pixmap with a mask. 


e void gtk_image_set_from_image (GtkImage *image, GdkImage *«gdk_image, GdkBitmap *mask) 


Set a GtkImage widget from Created a new GtkImage displaying a image with a mask. 


e void gtk_image_set_from_file (GtkImage *image, const gchar filename) 


Set a Image from Created a new GtkImage displaying the file filename. 


e void gtk_image_set_from_pixbuf (GtkImage *image, GdkPixbuf *pixbuf) 


See gtk_image_new_from_pixbuf() for details. 


e void gtk_image_set_from_stock (GtkImage «image, const gchar *stock_id, GtkIconSize size) 


See gtk_image_new_from_stock() for details. 


e void gtk_image_set_from_icon_set (GtkImage *image, GtkIconSet *icon_set, GtkIconSize size) 


See gtk_image_new_from_icon_set() for details. 
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e void gtk_image_set_from_animation (GtkImage «image, GdkPixbufAnimation *animation) 


Causes the GtkImage to display the given animation (or display nothing, if you set the animation to NULL). 


e void gtk_image_set_from_icon_name (GtkImage *image, const gchar *icon_name, GtkIconSize 
size) 


See gtk_image_new_from_icon_name() for details. 


e void gtk_image_set_pixel_size (GtkImage *image, gint pixel_size) 


Sets the pixel size to use for named icons. 


e GtkImageType gtk_image_get_storage_type (GtkImage *image) 


Gets the type of representation being used by the GtkImage to store image data. 


e void gtk_image_get_pixmap (GtkImage *image, GdkPixmap **pixmap, GdkBitmap **mask) 
Gets the pixmap and mask being displayed by the GtkImage. 


e void gtk_image_get_image (GtkImage *image, GdkImage **gdk_image, GdkBitmap **mask) 
Gets the GdkImage and mask being displayed by the GtkImage. 


e GdkPixbuf x gtk_image_get_pixbuf (GtkImage *image) 
Gets the GdkPixbuf being displayed by the GtkImage. 


e void gtk_image_get_stock (GtkImage *image, gchar x**stock_id, GtkIconSize «size) 


Gets the stock icon name and size being displayed by the GtkImage. 


e void gtk_image_get_icon_set (GtkImage *image, GtkIconSet **icon_set, GtkIconSize size) 


Gets the icon set and size being displayed by the GtkImage. 


e GdkPixbufAnimation * gtk_image_get_animation (GtkImage *image) 
Gets the GdkPixbufAnimation being displayed by the GtkImage. 


e void gtk_image_get_icon_name (GtkImage *image, G_CONST_RETURN gchar *xicon_name, Gt- 
kIconSize *size) 


Gets the icon name and size being displayed by the GtkImage. 


e gint gtk_image_get_pixel_size (GtkImage *image) 


Gets the pixel size used for named icons. 


6.27.2 Function Documentation 
6.27.2.1 void gtk_image_clear (GtkImage * image) 


Resets the image to be empty. 


Parameters: 


image [in] a GtkImage 


Returns: 


void 
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6.27.2.2 GdkPixbufAnimation* gtk_image_get_animation (GtkImage x image) 


Gets the GdkPixbufAnimation being displayed by the GtkImage. 


The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_ANIMATION (see gtk_- 
image _get_storage_type()). The caller of this function does not own a reference to the returned anima- 
tion. 


Parameters: 


image [in] a GtkImage 


Returns: 


the displayed animation, or NULL if the image is empty 


6.27.2.3 void gtk_image_get_icon_name (GtkImage x image, G_CONST_RETURN gchar ** 
icon_name, GtkIconSize x size) 


Gets the icon name and size being displayed by the GtkImage. 
The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_ICON_NAME (see gtk_- 
image_get_storage_type()). The returned string is owned by the GtkImage and should not be freed. 
Parameters: 

image [in] a GtkImage 

icon_name [out] place to store an icon name 


size [out] place to store an icon size 


Returns: 


void 


6.27.2.4 void gtk_image_get_icon_set (GtkImage x image, GtkIconSet xx icon_set, GtkIconSize x 
size) 


Gets the icon set and size being displayed by the GtkImage. 
The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_ICON_SET (see gtk_- 
image_get_storage_type()). 
Parameters: 
image [in] a GtkImage 
icon_set [out] location to store a GtkIconSet 


size [out] location to store a stock icon size 


Returns: 


void 
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6.27.2.5 void gtk_image_get_image (GtkImage x image, GdkImage xx gdk_image, GdkBitmap ** 
mask) 
Gets the GdkImage and mask being displayed by the GtkImage. 


The storage type of the image must be GTK_IMAGE_ EMPTY or GTK_IMAGE_IMAGE (see gtk_- 
image_get_storage_type()). The caller of this function does not own a reference to the returned image 
and mask. 


Parameters: 
image [in] a GtkImage 
gdk_image [out] return location for a GtkImage 


mask [out] return location for a GdkBitmap 


Returns: 


void 


6.27.2.6 GdkPixbufx gtk_image_get_pixbuf (GtkImage x image) 


Gets the GdkPixbuf being displayed by the GtkImage. 


The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_PIXBUF (see gtk_- 
image_get_storage_type()). The caller of this function does not own a reference to the returned pixbuf. 


Parameters: 


image [in] a GtkImage 


Returns: 


the displayed pixbuf, or NULL if the image is empty 


6.27.2.7 gint gtk_image_get_pixel_size (GtkImage * image) 


Gets the pixel size used for named icons. 


Parameters: 


image [in] a GtkImage 


Returns: 


the pixel size used for named icons. 


6.27.2.8 void gtk_image_get_pixmap (GtkImage x image, GdkPixmap ** pixmap, GdkBitmap ** 
mask) 


Gets the pixmap and mask being displayed by the GtkImage. 


The storage type of the image must be GTK_IMAGE_ EMPTY or GTK_IMAGE_PIXMAP (see gtk_- 
image_get_storage_type()). The caller of this function does not own a reference to the returned pixmap 
and mask. 
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Parameters: 
image [in] a GtkImage 
pixmap [out] location to store the pixmap, or NULL 


mask [out] location to store the mask, or NULL 


Returns: 


void 


6.27.2.9 void gtk_image_get_stock (GtkImage x image, gchar «* stock_id, GtkIconSize + size) 


Gets the stock icon name and size being displayed by the GtkImage. 
The storage type of the image must be GTK_IMAGE_EMPTY or GTK_IMAGE_STOCK (see gtk_- 
image_get_storage_type()). The returned string is owned by the GtkImage and should not be freed. 
Parameters: 

image [in] a GtkImage 

stock_id [out] place to store a stock icon name 


size [out] place to store a stock icon size 


Returns: 


void 


6.27.2.10 GtkImageType gtk_image_get_storage_type (GtkImage x image) 


Gets the type of representation being used by the GtkImage to store image data. 
If the GtkImage has no image data, the return value will be GTK_IMAGE_EMPTY. 


Parameters: 


image [in] a GtkImage 


Returns: 


image representation being used 


6.27.2.11 GtkWidgetx gtk_image_new (void) 


Creates a new empty GtkImage widget. 


Returns: 


a newly created GtkImage widget. 
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6.27.2.12 GtkWidget* gtk_image_new_from_animation (GdkPixbufAnimation x animation) 


Creates a GtkImage displaying the given animation. 


The GtkImage does not assume a reference to the animation; you still need to unref it if you own references. 
GtkImage will add its own reference rather than adopting yours. 


Note that the animation frames are shown using a timeout with G_LPRIORITY_DEFAULT. When using 
animations to indicate busyness, keep in mind that the animation will only be shown if the main loop is not 
busy with something that has a higher priority. 


Parameters: 


animation [in] an animation 


Returns: 


anew GtkImage widget 


6.27.2.13 GtkWidget« gtk_image_new_from_file (const gchar + filename) 


Creates a new GtkImage displaying the file filename. 


If the file isn’t found or can’t be loaded, the resulting GtkImage will display a "broken image" icon. This 
function never returns NULL, it always returns a valid GtkImage widget. 


If the file contains an animation, the image will contain an animation. 


If you need to detect failures to load the file, use gdk_pixbuf_new_from_file() to load the file yourself, then 
create the GtkImage from the pixbuf. (Or for animations, use gdk_pixbuf_animation_new_from_file()). 


The storage type (gtk_image_get_storage_type()) of the returned image is not defined, it will be whatever 
is appropriate for displaying the file. 


Parameters: 


filename [in] a filename 


Returns: 


a new GtkImage 


6.27.2.14 GtkWidget* gtk_image_new_from_icon_name (const gchar x icon_name, GtkIconSize 
size) 


Creates a GtkImage displaying an icon from the current icon theme. 


If the icon name isn’t known, a "broken image" icon will be displayed instead. If the current icon theme is 
changed, the icon will be updated appropriately. 


Parameters: 
icon_name [in] an icon name 
size [in] a stock icon size 
Returns: 


a new GtkImage displaying the themed icon 
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6.27.2.15 GtkWidget« gtk_image_new_from_icon_set (GtkIconSet x icon_set, GtkIconSize size) 


Creates a GtkImage displaying an icon set. 


Sample stock sizes are GTK_ICON_SIZE_MENU, GTK_ICON_SIZE_SMALL_TOOLBAR. Instead of 
using this function, usually it’s better to create a GtkIconFactory, put your icon sets in the icon factory, 
add the icon factory to the list of default factories with gtk_icon_factory_add_default(), and then use gtk_- 
image_new_from_stock(). This will allow themes to override the icon you ship with your application. 


The GtkImage does not assume a reference to the icon set; you still need to unref it if you own references. 
GtkImage will add its own reference rather than adopting yours. 


Parameters: 


icon_set [in] a GtkIconSet 


size [in] a stock icon size 


Returns: 


a new GtkImage 


6.27.2.16 GtkWidget« gtk_image_new_from_image (GdkImage « image, GdkBitmap * mask) 


Creates a GtkImage widget displaying a image with a mask. 


A GdkImage is a client-side image buffer in the pixel format of the current display. The GtkImage does 
not assume a reference to the image or mask; you still need to unref them if you own references. GtkImage 
will add its own reference rather than adopting yours. 


Parameters: 


pixmap [in] a GdkPixmap, or NULL 
mask [in] a GdkBitmap, or NULL 


Returns: 


a new GtkImage 


6.27.2.17 GtkWidget» gtk_image_new_from_pixbuf (GdkPixbuf x pixbuf) 


Creates a new GtkImage displaying pixbuf. 


The GtkImage does not assume a reference to the pixbuf; you still need to unref it if you own references. 
GtkImage will add its own reference rather than adopting yours. 


Note that this function just creates an GtkImage from the pixbuf. The GtkImage created will not react to 
state changes. Should you want that, you should use gtk_image_new_from_icon_set(). 


Parameters: 


pixbuf [in] a GdkPixbuf, or NULL 


Returns: 


a new GtkImage 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.27 GtkImage 273 


6.27.2.18 GtkWidget« gtk_image_new_from_pixmap (GdkPixmap + pixmap, GdkBitmap * mask) 


Creates a GtkImage widget displaying pixmap with a mask. 
A GdkPixmap is a server-side image buffer in the pixel format of the current display. The GtkImage does 
not assume a reference to the pixmap or mask; you still need to unref them if you own references. GtkImage 
will add its own reference rather than adopting yours. 
Parameters: 

pixmap [in] a GdkPixmap, or NULL 

mask [in] a GdkBitmap, or NULL 


Returns: 


a new GtkImage 


6.27.2.19 GtkWidget* gtk_image_new_from_stock (const gchar x stock_id, GtkIconSize size) 


Creates a GtkImage displaying a stock icon. 


Sample stock icon names are GTK_STOCK_OPEN, GTK_STOCK_QUIT. Sample stock sizes are GTK_- 
ICON_SIZE_MENU, GTK_ICON_SIZE_SMALL_ TOOLBAR. If the stock icon name isn't known, the 
image will be empty. You can register your own stock icon names, see gtk_icon_factory_add_default() and 
gtk_icon_factory_add(). 


Parameters: 
stock_id [in] a stock icon name 


size [in] a stock icon size 


Returns: 


a new GtkImage displaying the stock icon 


6.27.2.20 void gtk_image_set_from_animation (GtkImage « image, GdkPixbufAnimation x 
animation) 


Causes the GtkImage to display the given animation (or display nothing, if you set the animation to NULL). 


Parameters: 
image [in] a GtkImage 


animation [in] the GdkPixbufAnimation 


Returns: 


void 
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6.27.2.21 void gtk_image_set_from_file (GtkImage x image, const gchar + filename) 


Set a Image from Created a new GtkImage displaying the file filename. 


See gtk_image_new_from_file() for details. 


Parameters: 

image [in] a GtkImage 

filename [in] a filename or NULL 
Returns: 


void 


6.27.2.22 void gtk_image set_from_icon_name (GtkImage x image, const gchar x icon_name, 
GtkIconSize size) 


See gtk_image_new_from_icon_name() for details. 


Parameters: 
image [in] a GtkImage 
icon_name [in] an icon name 


size [in] an icon size 


Returns: 


void 


6.27.2.23 void gtk_image_set_from_icon_set (GtkImage x image, GtkIconSet x icon_set, 
GtkIconSize size) 


See gtk_image_new_from_icon_set() for details. 


See gtk_image_new_from_icon_set() for details. 


Parameters: 
image [in] a GtkImage 
icon_set [in] a GtkIconSet 


size [in] a stock icon size 


Returns: 


void 


6.27.2.24 void gtk_image_set_from_image (GtkImage x image, GdkImage « gdk_image, 
GdkBitmap * mask) 


Set a GtkImage widget from Created a new GtkImage displaying a image with a mask. 


See gtk_image_new_from_image() for details. 
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Parameters: 


image [in] a GtkImage 
gdk_image [in] a GdkImage or NULL 
mask [in] a GdkBitmap or NULL 


Returns: 


void 


6.27.2.25 void gtk_ image set_from_pixbuf (GtkImage x image, GdkPixbuf x pixbuf) 


See gtk_image_new_from_pixbuf() for details. 


See gtk_image_new_from_pixbuf() for details. 


Parameters: 


image [in] a GtkImage 
pixbuf [in] a GdkPixbuf or NULL 


Returns: 


void 


6.27.2.26 void gtk_image_set_from_pixmap (GtkImage x image, GdkPixmap * pixmap, 
GdkBitmap x mask) 


Sets a GtkImage widget displaying pixmap with a mask. 


See gtk_image_new_from_pixmap() for details. 


Parameters: 
image [in] a GtkImage 
pixmap [in] a GdkPixmap or NULL 
mask [in] a GdkBitmap or NULL 


Returns: 


void 


6.27.2.27 void gtk_image_set_from_stock (GtkImage x image, const gchar x stock_id, GtkIconSize 
size) 


See gtk_image_new_from_stock() for details. 


See gtk_image_new_from_stock() for details. 


Parameters: 
image [in] a GtkImage 


stock_id [in] a stock icon name 
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size [in] a stock icon size 


Returns: 


void 


6.27.2.28 void gtk_image set_pixel_size (GtkImage x image, gint pixel_size) 


Sets the pixel size to use for named icons. 


Tf the pixel size is set to a value != -1, it is used instead of the icon size set by gtk_image_set_from_icon_- 
name(). 


Parameters: 
image [in] a GtkImage 


pixel_size [in] the new pixel size 


Returns: 


void 
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6.28 GtkLabel 


6.28.1 Detailed Description 


The GtkLabel widget displays a small amount of text. 


As the name implies, most labels are used to label another widget such as a GtkButton, a GtkMenultem, or 
a GtkOptionMenu. 


This label is underline di 


Figure 6.4: GtkLabel 


Markup (styled text) 


To make it easy to format text in a label (changing colors, fonts, etc.), label text can be provided in a 
simple markup format. Here’s how to create a label with a small font: label = gtk_label_new (NULL); 
gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); 


(See complete documentation of available tags in the Pango manual.) 


The markup passed to gtk_label_set_markup() must be valid; for example, literal </>/& characters must 
be escaped as <, >, and &. If you pass text obtained from the user, file, or a network to gtk_label_set_- 
markup(), you’ll want to escape it with g_markup_escape_text() or g markup_printf_escaped(). 


Markup strings are just a convenient way to set the PangoAttrList on a label; gtk_label_set_attributes() 
may be a simpler way to set attributes in some cases. Be careful though; PangoAttrList tends to cause 
internationalization problems, unless you're applying attributes to the entire string (i.e. unless you set the 
range of each attribute to [0, G_MAXINT)). The reason is that specifying the start_index and end_index 
for a PangoAttribute requires knowledge of the exact string being displayed, so translations will cause 
problems. 


Selectable labels 
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Labels can be made selectable with gtk_label_set_selectable(). Selectable labels allow the user to copy the 
label contents to the clipboard. Only labels that contain useful-to-copy information, such as error messages, 
should be made selectable. 


Text layout 


A label can contain any number of paragraphs, but will have performance problems if it contains more than 
a small number. Paragraphs are separated by newlines or other paragraph separators understood by Pango. 


Labels can automatically wrap text 1f you call gtk_label_set_line_wrap(). 


gtk_label_set_justify() sets how the lines in a label align with one another. If you want to set how the label 
as a whole aligns in its available space, see gtk_misc_set_alignment(). 


Is inheritted from GtkLabel and expanded while TextSlide function is added. Modified for style of mobile 
UI 


Code Example 


form = gtk_form_new () 

GtkWidget x*label; 

label = gtk_label_new(""); 

gtk_label_set_text (GTK_LABEL (label), "Label?; 
gtk_widget_set_size_request (label, 20, 50); 
gtk_label_set_focusable (GTK_LABEL (label), TRUE); 
gtk_label_set_slide_mode(GTK_LABEL (label), STYLE_SLIDE_ON_FOCUS) ; 
gtk_label_set_slide_repeat_count (GTK_LABEL (label), SLIDE_COUNT_INDEFINITE ); //contineous slide 
gtk_form_contain_add (form, label); 

gtk_widget_show (form); 

gtk_widget_show (label); 


e gtk_label_set_slide_mode This fuction sets slide mode. 


e gtk_label_get_slide_mode This fuction gets slide mode. 


e gtk_label_set_focusable This function set if label can focus 


e gtk_label_get_focusable This function get the focus setting 


e gtk_label_set_slide pixel_interval This function set interval of label’s sliding text. 


e gtk_label_get_slide _pixel_interval This function get interval of label’s sliding text. 


Gtk_label_set_slide_mode also have two types parameter, as following: 1.STYLE_SLIDE_ON_FOCUS 
2.STYLE_SLIDE_ALWAYS 


Note: If the STYLE_SLIDE_ON_FOCUS is the mode you prefer, you must call gtk_label_set_focusable 
to set label focusable at initialization. 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkLabel 


GtkLabel instance structure. 


e struct _GtkLabelClass 


GTK Native GtkLabel instance class structure. 
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Enumerations 


e enum GtkSlideMode { STYLE_SLIDE_ON_FOCUS, STYLE_SLIDE_ALWAYS } 


Slide mode State enumeration. 


e enum GtkSlideCountMode [ SLIDE_COUNT_INDEFINITE = -1, SLIDE_COUNT_NO_ SLIDE = 
0} 


Slide count mode. 


+ enum GtkSlideState 


Slide State enumeration internal control. 


Functions 


e GtkWidget * gtk_label_new (const gchar «str) 


Creates a new label with the given text inside it. 


GtkWidget x gtk_label_new_with_mnemonic (const gchar *str) 


[Deprecated] Creates a new GtkLabel, containing the text in str. 


void gtk_label_set_slide_mode (GtkLabel xlabel, GtkSlideMode slidemode) 


This fuction sets slide mode. 


GtkSlideMode gtk_label_get_slide_mode (GtkLabel label) 


This fuction gets slide mode. 


void gtk_label_set_text (GtkLabel «label, const gchar str) 
Sets the text within the GtkLabel widget. 


G_CONST_RETURN gchar x gtk_label_get_text (GtkLabel label) 


Fetches the text from a label widget, as displayed on the screen. 


void gtk_label_set_attributes (GtkLabel «label, PangoAttrList «attrs) 


Sets a PangoAttrList; the attributes in the list are applied to the label text. 


PangoAttrList x gtk_label_get_attributes (GtkLabel «label) 


Gets the attribute list that was set on the label using gtk_label_set_attributes(), if any. 


void gtk_label_set_label (GtkLabel «label, const gchar «str) 


Sets the text of the label. 


G_CONST_RETURN gchar x gtk _label_get_label (GtkLabel «label) 


Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango 
markup. 


void gtk_label_set_markup (GtkLabel «label, const gchar «str) 


Parses str which is marked up with the Pango text markup language, setting the label’s text and attribute 
list based on the parse results. 
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void gtk_label_set_use_markup (GtkLabel x*label, gboolean setting) 


Sets whether the text of the label contains markup in Pango’s text markup language. 


gboolean gtk_label_get_use_markup (GtkLabel *label) 


Returns whether the label’s text is interpreted as marked up with the Pango text markup language. 


void gtk_label_set_use_underline (GtkLabel «label, gboolean setting) 


If true, an underline in the text indicates the next character should be used for the mnemonic accelerator 
key. 


gboolean gtk_label_get_use_underline (GtkLabel «label) 


Returns whether an embedded underline in the label indicates a mnemonic. 


void gtk_label_set_markup_with_mnemonic (GtkLabel label, const gchar str) 


[Deprecated] Parses str which is marked up with the Pango text markup language, setting the label’s text 
and attribute list based on the parse results. 


guint gtk_label_get_mnemonic_keyval (GtkLabel label) 


[Deprecated] If the label has been set so that it has an mnemonic key this function returns the keyval used 
for the mnemonic accelerator. 


void gtk_label_set_mnemonic_widget (GtkLabel «label, GtkWidget «widget) 


[Deprecated] If the label has been set so that it has an mnemonic key (using i.e. 


GtkWidget x gtk_label_get_mnemonic_widget (GtkLabel «label) 


[Deprecated] Retrieves the target of the mnemonic (keyboard shortcut) of this label. 


void gtk_label_set_text_with_mnemonic (GtkLabel «label, const gchar *str) 


[Deprecated] Sets the label’s text from the string str. 


void gtk_label_set_justify (GtkLabel label, GtkJustification jtype) 


Sets the alignment of the lines in the text of the label relative to each other. 


GtkJustification gtk_label_get_justify (GtkLabel x*label) 


Returns the justification of the label. 


void gtk_label_set_ellipsize (GtkLabel «label, PangoEllipsizeMode mode) 


n" 


Sets the mode used to ellipsize (add an ellipsis: 
entire string. 


...") to the text if there is not enough space to render the 


PangoEllipsizeMode gtk_label_get_ellipsize (GtkLabel xlabel) 


Returns the ellipsizing position of the label. 


void gtk_label_set_width_chars (GtkLabel «label, gint n_chars) 


Sets the desired width in characters of label to n_chars. 


gint gtk_label_get_width_chars (GtkLabel «label) 


Retrieves the desired width of label, in characters. 


void gtk_label_set_max_width_chars (GtkLabel «label, gint n_chars) 
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Sets the desired maximum width in characters of label to n_chars. 


e gint gtk_label_get_max_width_chars (GtkLabel xlabel) 


Retrieves the desired maximum width of label, in characters. 


e void gtk_label_set_pattern (GtkLabel «label, const gchar *pattern) 


The pattern of underlines you want under the existing text within the GtkLabel widget. 


e void gtk_label_set_line_wrap (GtkLabel xlabel, gboolean wrap) 
Toggles line wrapping within the GtkLabel widget. 


e gboolean gtk_label_get_line_wrap (GtkLabel «label) 


Returns whether lines in the label are automatically wrapped. 


e void gtk_label_set_line_wrap_mode (GtkLabel label, PangoWrapMode wrap_mode) 


If line wrapping is on this controls how the line wrapping is done. 


e PangoWrapMode gtk _label_get_line_wrap_mode (GtkLabel label) 


Returns line wrap mode used by the label. 


e void gtk_label_set_selectable (GtkLabel «label, gboolean setting) 


Selectable labels allow the user to select text from the label, for copy-and-paste. 


e gboolean gtk_label_get_selectable (GtkLabel xlabel) 
Gets the value set by gtk_label_set_selectable(). 


e void gtk_label_set_angle (GtkLabel «label, gdouble angle) 


Sets the angle of rotation for the label. 


e gdouble gtk_label_get_angle (GtkLabel xlabel) 


Gets the angle of rotation for the label. 


e void gtk_label_select_region (GtkLabel xlabel, gint start_offset, gint end_offset) 


Selects a range of characters in the label, if the label is selectable. 


e gboolean gtk_label_get_selection_bounds (GtkLabel x*label, gint start, gint *end) 


Gets the selected range of characters in the label, returning TRUE if there's a selection. 


e PangoLayout « gtk_label_get_layout (GtkLabel *label) 
Gets the PangoLayout used to display the label. 


e void gtk_label_get_layout_offsets (GtkLabel «label, gint «x, gint xy) 


Obtains the coordinates where the label will draw the PangoLayout representing the text in the label; useful 
to convert mouse events into coordinates inside the PangoLayout, e.g. 


e void gtk_label_set_single_line_mode (GtkLabel «label, gboolean single_line_mode) 


Sets whether the label is in single line mode. 


e gboolean gtk_label_get_single_line_mode (GtkLabel «label) 


Returns whether the label is in single line mode. 
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void gtk_label_set_focusable (GtkLabel *label, gboolean focus_yes_no) 


Sets whether the label is focusable. 


gboolean gtk_label_get_focusable (GtkLabel *label) 


Returns whether the label is focusable. 


void gtk_label_set_time_out (GtkLabel x*label, guint time_out) 


Sets the value of the time_out of the timer which control the slide speed. 


guint gtk_label_get_time_out (GtkLabel x*label) 


Returns the time_out value of timer which control the slide of label’s text. 


void gtk_label_set_slide_repeat_count (GtkLabel x*label, gint slide_count) 


Sets the Label Text Slide repeat count. 


gint gtk_label_get_slide_repeat_count (GtkLabel «label) 


Returns the Label Text Slide repeat count. 


void gtk_label_set_bold (GtkLabel «label, gboolean bold) 
Sets the font style (BOLD property) of the text within the GtkLabel widget. 


gboolean gtk_label_get_bold (GtkLabel xlabel) 
Gets the font style (BOLD property) of the text within the GtkLabel widget. 


void gtk_label_set_slide_pixel_interval (GtkLabel «label, gint interval) 


Sets the marquee moving interval in pixels. 


int gtk_label_get_slide_pixel_interval (GtkLabel xlabel) 


Returns the marquee moving interval in pixels. 


void gtk_label_set_slide_state (GtkLabel «label, GtkSlideState slidestate) 
Sets the label Slide State. 


GtkSlideState gtk_label_get_slide_state (GtkLabel xlabel) 


Returns the label Slide State. 


6.28.2 Enumeration Type Documentation 


6.28.2.1 enum GtkSlideCountMode 


Slide count mode. 


Enumerator: 


SLIDE_COUNT_INDEFINITE Slide indefinitely. 
SLIDE_COUNT_NO_SLIDE No sliding. 
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6.28.2.2 enum GtkSlideMode 
Slide mode State enumeration. 


Enumerator: 


STYLE_SLIDE_ON_FOCUS Slide only if it gets the focus. 
STYLE_SLIDE_ALWAYS Always slide. 


6.28.2.3 enum GtkSlideState 


Slide State enumeration internal control. 


6.28.3 Function Documentation 
6.28.3.1 gdouble gtk_label_get_angle (GtkLabel x label) 


Gets the angle of rotation for the label. 


See gtk_label_set_angle() 


Parameters: 


label [in] a GtkLabel 


Returns: 


the angle of rotation for the label 


6.28.3.2 PangoAttrList« gtk_label_get_attributes (GtkLabel « label) 


Gets the attribute list that was set on the label using gtk_label_set_attributes(), if any. 


This function does not reflect attributes that come from the labels markup (see gtk_label_set_markup()). If 
you want to get the effective attributes for the label, use pango_layout_get_attribute (gtk_label_get_layout 
(label)). 


Parameters: 


label [in] a GtkLabel 


Returns: 


the attribute list, or NULL if none was set. 


6.28.3.3 gboolean gtk_label_get_bold (GtkLabel « label) 
Gets the font style (BOLD property) of the text within the GtkLabel widget. 


Parameters: 


label [in] a GtkLabel 
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Returns: 


TURE the font style (BOLD property) is set,or not. 


See also: 


gtk_label_set_bold() 


Since 


LIMO RI 


6.28.3.4 PangoEllipsizeMode gtk_label_get_ellipsize (GtkLabel « label) 


Returns the ellipsizing position of the label. 
See gtk_label_set_ellipsize(). 
Parameters: 


label [in] a GtkLabel 


Returns: 


PangoEllipsizeMode 


6.28.3.5 gboolean gtk_label_get_focusable (GtkLabel x label) 


Returns whether the label is focusable. 
Parameters: 

label [in] a GtkLabel 
Returns: 

TRUE, the label can be focused, or not. 
See also: 


gtk_label_set_focusable() 


Since 


LIMO R1 


6.28.3.6 GtkJustification gtk_label_get_justify (GtkLabel « label) 
Returns the justification of the label. 
See gtk_label_set_justify(). 
Parameters: 
label [in] a GtkLabel 


Returns: 


GtkJustification 
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6.28.3.7 G_CONST_RETURN gcharx gtk_label_get_label (GtkLabel x label) 


Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango 
markup. 


(See gtk_label_get_text(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


the text of the label widget. This string is owned by the widget and must not be modified or freed. 


6.28.3.8 PangoLayout« gtk_label_get_layout (GtkLabel « label) 


Gets the PangoLayout used to display the label. 


The layout is useful to e.g. convert text positions to pixel positions, in combination with gtk _label_get_- 
layout_offsets(). The returned layout is owned by the label so need not be freed by the caller. 


Parameters: 


label [in] a GtkLabel 


Returns: 


the PangoLayout for this label 


6.28.3.9 void gtk _label_get_layout_offsets (GtkLabel x label, gint x x, gint x y) 
Obtains the coordinates where the label will draw the PangoLayout representing the text in the label; useful 
to convert mouse events into coordinates inside the PangoLayout, e.g. 


to take some action if some part of the label is clicked. Of course you will need to create a GtkEventBox to 
receive the events, and pack the label inside it, since labels are a GTK_NO_WINDOW widget. Remember 
when using the PangoLayout functions you need to convert to and from pixels using PANGO_PIXELS() 
or PANGO_SCALE. 


Parameters: 


label [in] a GtkLabel 
x [out] location to store X offset of layout, or NULL 
y [out] location to store Y offset of layout, or NULL 


Returns: 


label coordinates 


6.28.3.10 gboolean gtk_label_get_line_wrap (GtkLabel x label) 


Returns whether lines in the label are automatically wrapped. 


See gtk_label_set_line_wrap(). 
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Parameters: 


label [in] a GtkLabel 


Returns: 


TRUE if the lines of the label are automatically wrapped. 


6.28.3.11 PangoWrapMode gtk_label_get_line_wrap_mode (GtkLabel x label) 


Returns line wrap mode used by the label. 


See gtk_label_set_line_wrap_mode(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


TRUE if the lines of the label are automatically wrapped. 


6.28.3.12 gint gtk_label_get_max_width_chars (GtkLabel « label) 


Retrieves the desired maximum width of label, in characters. 


See gtk_label_set_width_chars(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


the maximum width of the label in characters. 


6.28.3.13 guint gtk_label_get_mnemonic_keyval (GtkLabel « label) 


[Deprecated] If the label has been set so that it has an mnemonic key this function returns the keyval used 
for the mnemonic accelerator. 


If there is no mnemonic set up it returns GDK_VoidSymbol. 


Parameters: 


label [in] a GtkLabel 


Returns: 


GDK keyval usable for accelerators, or GDK_VoidSymbol 


Deprecated 
LIMO R1 
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6.28.3.14 GtkWidgetx gtk_label_get_mnemonic_widget (GtkLabel x label) 
[Deprecated] Retrieves the target of the mnemonic (keyboard shortcut) of this label. 
See gtk_label_set_mnemonic_widget(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


the target of the label’s mnemonic, or NULL if none has been set and the default algorithm will be 
used. 


Deprecated 
LIMO R1 


6.28.3.15 gboolean gtk_label_get_selectable (GtkLabel « label) 


Gets the value set by gtk_label_set_selectable(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


TRUE if the user can copy text from the label 


6.28.3.16 gboolean gtk_label_get_selection_bounds (GtkLabel « label, gint x start, gint x end) 


Gets the selected range of characters in the label, returning TRUE if there’s a selection. 


Parameters: 


label [in] a GtkLabel 
start [out] return location for start of selection, as a character offset 


end [out] return location for end of selection, as a character offset 


Returns: 


TRUE if selection is non-empty 


6.28.3.17 gboolean gtk_label_get_single_line_mode (GtkLabel x label) 


Returns whether the label is in single line mode. 


Parameters: 


label [in] a GtkLabel 


Returns: 


TRUE when the label is in single line mode. 
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6.28.3.18 GtkSlideMode gtk_label_get_slide_mode (GtkLabel x label) 


This fuction gets slide mode. 
Parameters: 

label [in]specified the GtkLabel 
Returns: 

This Funtion returns SlideMode 
See also: 


gtk_label_set_slide_mode() 


Since 


LIMO RI 


6.28.3.19 int gtk_label_get_slide_pixel_interval (GtkLabel « label) 


Returns the marquee moving interval in pixels. 


Parameters: 
label [in] a GtkLabel 
Returns: 


Slide moving pixel interval 


See also: 


gtk_label_set_slide_pixel_interval() 


Since 


LIMO R1 


6.28.3.20 gint gtk_label_get_slide_repeat_count (GtkLabel x label) 


Returns the Label Text Slide repeat count. 
Parameters: 
label [in] a GtkLabel. 


Returns: 
slide_count Sliding count. Value -1 (define SLIDE_COUNT_INDEFINITE) represents the Indefinite 
repeat. Value 0 (define SLIDE_COUNT_NO_SLIDE) represents slide off state. 

See also: 


gtk_label_set_slide_repeat_count() 


Since 


LIMO R1 
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6.28.3.21 GtkSlideState gtk_label_get_slide_state (GtkLabel « label) 


Returns the label Slide State. 


Parameters: 


label [in] a GtkLabel 


Returns: 


label Slide State 


See also: 


gtk_label_set_slide_state() 


Since 


LIMO R1 


6.28.3.22  G_CONST_RETURN gchar» gtk_label_get_text (GtkLabel x label) 


Fetches the text from a label widget, as displayed on the screen. 


This does not include any embedded underlines indicating mnemonics or Pango markup. (See gtk_label_- 
get_label()) 


Parameters: 


label [in] a GtkLabel 


Returns: 


the text in the label widget. This is the internal string used by the label, and must not be modified. 


6.28.3.23 guint gtk_label_get_time_out (GtkLabel x label) 


Returns the time_out value of timer which control the slide of label’s text. 


Parameters: 


label [in] a GtkLabel 


Returns: 


value The time_out value of timer. 


See also: 


gtk_label_set_time_out() 


Since 


LIMO RI 
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6.28.3.24 gboolean gtk_label_get_use_markup (GtkLabel x label) 


Returns whether the label’s text is interpreted as marked up with the Pango text markup language. 


See gtk_label_set_use_markup(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


TRUE if the label’s text will be parsed for markup. 


6.28.3.25 gboolean gtk_label_get_use_underline (GtkLabel « label) 


Returns whether an embedded underline in the label indicates a mnemonic. 


See gtk_label_set_use_underline(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


TRUE whether an embedded underline in the label indicates the mnemonic accelerator keys. 


6.28.3.26 gint gtk_label_get_width_chars (GtkLabel « label) 


Retrieves the desired width of label, in characters. 


See gtk_label_set_width_chars(). 


Parameters: 


label [in] a GtkLabel 


Returns: 


the width of the label in characters. 


6.28.3.27 GtkWidget» gtk_label_new (const gchar x str) 


Creates a new label with the given text inside it. 


You can pass NULL to get an empty label widget. 


Parameters: 


str [in] The text of the label 


Returns: 


the new GtkLabel 
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6.28.3.28 GtkWidget« gtk_label_new_with_mnemonic (const gchar x str) 


[Deprecated] Creates a new GtkLabel, containing the text in str. 


If characters in str are preceded by an underscore, they are underlined. If you need a literal underscore 
character in a label, use *__” (two underscores). The first underlined character represents a keyboard accel- 
erator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, 
or explicitly using gtk_label_set_mnemonic_widget(). 


If gtk_label_set_mnemonic_widget() is not called, then the first activatable ancestor of the GtkLabel will 
be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or 
menu item will automatically become the mnemonic widget and be activated by the mnemonic. 


Parameters: 


str [in] The text of the label, with an underscore in front of the mnemonic character 


Returns: 

the new GtkLabel 
Deprecated 

LIMO R1 


6.28.3.29 void gtk_label_select_region (GtkLabel x label, gint start_offset, gint end_offset) 


Selects a range of characters in the label, if the label is selectable. 


See gtk_label_set_selectable(). If the label is not selectable, this function has no effect. If start_offset or 
end_offset are -1, then the end of the label will be substituted. 


Parameters: 
label [in] a GtkLabel 
start_offset start [in] offset (in characters not bytes) 
end_offset [in] end offset (in characters not bytes) 
Returns: 


void 


6.28.3.30 void gtk_label_set_angle (GtkLabel x label, gdouble angle) 


Sets the angle of rotation for the label. 


An angle of 90 reads from from bottom to top, an angle of 270, from top to bottom. The angle setting for 
the label is ignored if the label is selectable, wrapped, or ellipsized. 


Parameters: 


label [in]a GtkLabel 


angle [in] the angle that the baseline of the label makes with the horizontal, in degrees, measured 
counterclockwise 


Returns: 


void 
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6.28.3.31 void gtk_label_set_attributes (GtkLabel x label, PangoAttrList x attrs) 


Sets a PangoAttrList; the attributes in the list are applied to the label text. 
The attributes set with this function will be ignored if the "use_underline" property or the "use_markup" 
property is TRUE. 
Parameters: 
label [in] a GtkLabel 
attrs [in] a PangoAttrList 


Returns: 


void 


6.28.3.32 void gtk_label_set_bold (GtkLabel x label, gboolean bold) 


Sets the font style (BOLD property) of the text within the GtkLabel widget. 


Parameters: 
label [in] a GtkLabel 
bold [in] TRUE bold property 


See also: 


gtk_label_get_boldQ 


Since 


LIMO R1 


6.28.3.33 void gtk_label_set_ellipsize (GtkLabel x label, PangoEllipsizeMode mode) 


" 


Sets the mode used to ellipsize (add an ellipsis: 
entire string. 


...) to the text if there is not enough space to render the 


Parameters: 
label [in] a GtkLabel 
mode [in] a PangoEllipsizeMode 


Returns: 


void 


6.28.3.34 void gtk_label_set_focusable (GtkLabel x label, gboolean focus_yes_no) 


Sets whether the label is focusable. 
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Parameters: 
label [in] a GtkLabel 
focus_yes_no [in] TRUE if the label can be focused,FALSE or not. 


Since 


LIMO RI 


6.28.3.35 void gtk_label_set_justify (GtkLabel x label, GtkJustification jtype) 


Sets the alignment of the lines in the text of the label relative to each other. 
GTK_JUSTIFY_LEFT is the default value when the widget is first created with gtk_label_new(). If you 
instead want to set the alignment of the label as a whole, use gtk_misc_set_alignment() instead. gtk_- 
label_set_justify( has no effect on labels containing only a single line. 
Parameters: 

label [in] a GtkLabel 

Jtype [in] a GtkJustification 


Returns: 


void 


6.28.3.36 void gtk_label_set_label (GtkLabel « label, const gchar + str) 


Sets the text of the label. 
The label is interpreted as including embedded underlines and/or Pango markup depending on the values 
of label->use_underline and label->use_markup. 
Parameters: 
label [in] a GtkLabel 


str [in] the new text to set for the label 


Returns: 


void 


6.28.3.37 void gtk_label_set_line_wrap (GtkLabel « label, gboolean wrap) 


Toggles line wrapping within the GtkLabel widget. 


TRUE makes it break lines if text exceeds the widget’s size. FALSE lets the text get cut off by the edge of 
the widget if it exceeds the widget size. 


Note that setting line wrapping to TRUE does not make the label wrap at its parent container’s width, 
because GTK+ widgets conceptually can’t make their requisition depend on the parent container’s size. 
For a label that wraps at a specific position, set the label’s width using gtk_widget_set_size_request(). 
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Parameters: 


label [in] a GtkLabel 
wrap [in] boolean TRUE wrappS the text, or FALSE 


Returns: 


void 


6.28.3.38 void gtk_label_set_line_wrap_mode (GtkLabel x label, PangoWrapMode wrap_mode) 


If line wrapping is on this controls how the line wrapping is done. 


The default is PANGO_WRAP_WORD which means wrap on word boundaries. 


Parameters: 

label [in] a GtkLabel 

wrap_mode [in] the line wrapping mode 
Returns: 


void 


6.28.3.39 void gtk_label_set_markup (GtkLabel x label, const gchar x str) 
Parses str which is marked up with the Pango text markup language, setting the label’s text and attribute 
list based on the parse results. 


If the str is external data, you may need to escape it with g markup_escape_text() or g_markup_printf_- 
escaped(): 


char xmarkup; 


markup = g_markup_printf_escaped ("<span style=\"italic\">%s</span>", str); 
gtk_label_set_markup (GTK_LABEL (label), markup); 
g_free (markup) ; 


Parameters: 

label [in] a GtkLabel 

str [in] a markup string (see Pango markup format) 
Returns: 


void 


6.28.3.40 void gtk_label_set_markup_with_mnemonic (GtkLabel x label, const gchar + str) 
[Deprecated] Parses str which is marked up with the Pango text markup language, setting the label’s text 
and attribute list based on the parse results. 


If characters in str are preceded by an underscore, they are underlined indicating that they represent a 
keyboard accelerator called a mnemonic. 


The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_- 
label_set_mnemonic_widget(). 
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Parameters: 
label [in] a GtkLabel 


str [in] a markup string 


Returns: 


TRUE if the label’s text will be parsed for markup. 


Deprecated 
LIMO R1 


6.28.3.41 void gtk_label_set_max_width_chars (GtkLabel x label, gint n_chars) 


Sets the desired maximum width in characters of label to n_chars. 


Parameters: 
label [in] a GtkLabel 


n_chars [in] the new desired maximum width, in characters. 


Returns: 


void 


6.28.3.42 void gtk_label_set_mnemonic_widget (GtkLabel x label, GtkWidget « widget) 


[Deprecated] If the label has been set so that it has an mnemonic key (using i.e. 


gtk_label_set_markup_with_mnemonic(), gtk_label_set_text_with_mnemonic(), gtk_label_new_with_- 
mnemonic() or the "use_underline" property) the label can be associated with a widget that is the target of 
the mnemonic. When the label is inside a widget (like a GtkButton or a GtkNotebook tab) it is automati- 
cally associated with the correct widget, but sometimes (i.e. when the target is a GtkEntry next to the label) 
you need to set it explicitly using this function. 


The target widget will be accelerated by emitting "mnemonic_activate" on it. The default handler for this 
signal will activate the widget if there are no mnemonic collisions and toggle focus between the colliding 
widgets otherwise. 
Parameters: 

label [in] a GtkLabel 

widget [in] the target Gtk Widgetl 


Returns: 


void 


Deprecated 
LIMO R1 
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6.28.3.43 void gtk_label_set_pattern (GtkLabel x label, const gchar x pattern) 


The pattern of underlines you want under the existing text within the GtkLabel widget. 


For example if the current text of the label says "FooBarBaz" passing a pattern of " " will underline 
"Foo" and "Baz" but not "Bar". 


Parameters: 
label [in] a GtkLabel 


pattern [in] The pattern as described above. 


Returns: 


void 


6.28.3.44 void gtk_label_set_selectable (GtkLabel « label, gboolean setting) 


Selectable labels allow the user to select text from the label, for copy-and-paste. 


Parameters: 
label [in] a GtkLabel 
setting [in] TRUE to allow selecting text in the label 


Returns: 


void 


6.28.3.45 void gtk_label_set_single_line_mode (GtkLabel x label, gboolean single_line_mode) 


Sets whether the label is in single line mode. 


Parameters: 
label [in] a GtkLabel 
single_line_mode [in] TRUE if the label should be in single line mode 


Returns: 


void 


6.28.3.46 void gtk_label_set_slide_mode (GtkLabel x label, GtkSlideMode slidemode) 
This fuction sets slide mode. 


Parameters: 
label [in] specifies the GtkLabel 


slidemode[in] specifies the slidemode 
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See also: 


gtk_label_get_slide_mode() 


Since 


LIMO R1 


6.28.3.47 void gtk_label_set_slide_pixel_interval (GtkLabel x label, gint interval) 
Sets the marquee moving interval in pixels. 


Parameters: 


label [in] a GtkLabel 


slide [in] advancing pixel interval 


See also: 


gtk_label_get_slide_pixel_interval() 


Since 


LIMO R1 


6.28.3.48 void gtk_label_set_slide_repeat_count (GtkLabel x label, gint slide_count) 


Sets the Label Text Slide repeat count. 


Parameters: 


label [in] a GtkLabel. 


slide_count Sliding count. Value -1 (define SLIDE_COUNT_INDEFINITE) represents the Indefinite 
repeat. Value 0 (define SLIDE_COUNT_NO_SLIDE) should be passed to disable sliding. 


Returns: 


void 


See also: 


gtk_label_get_slide_repeat_count() 


Since 


LIMO R1 


6.28.3.49 void gtk_label_set_slide_state (GtkLabel x label, GtkSlideState slidestate) 


Sets the label Slide State. 


Parameters: 


label [in] a GtkLabel 
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slidestate [in] a SlideState 
Returns: 
void 


See also: 


gtk_label_get_slide_state() 


Since 


LIMO R1 


6.28.3.50 void gtk_label_set_text (GtkLabel x label, const gchar x str) 


Sets the text within the GtkLabel widget. 
It overwrites any text that was there before. 


This will also clear any previously set mnemonic accelerators. 


Parameters: 
label [in] a GtkLabel 


str [in] The text you want to set. 


Returns: 


void 


6.28.3.51 void gtk_label_set_text_with_mnemonic (GtkLabel x label, const gchar + str) 


[Deprecated] Sets the label’s text from the string str. 
If characters in str are preceded by an underscore, they are underlined indicating that they represent a 
keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, 
chosen automatically, or explicitly using gtk_label_set_mnemonic_widget(). 
Parameters: 

label [in] a GtkLabel 


str [in] a string 


Returns: 


void 


Deprecated 
LIMO R1 
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6.28.3.52 void gtk_label_set_time_out (GtkLabel x label, guint time_out) 


Sets the value of the time_out of the timer which control the slide speed. 


param time_out should be larger than 3. 


Parameters: 


label [in] a GtkLabel 


time_out [in] The value to set to the timer. 


See also: 


gtk_label_get_time_out() 


Since 


LIMO R1 


6.28.3.53 void gtk_label_set_use_markup (GtkLabel x label, gboolean setting) 


Sets whether the text of the label contains markup in Pango’s text markup language. 


See gtk _label_set_markup(). 


Parameters: 


label [in] a GtkLabel 
setting [in] TRUE if the label’s text should be parsed for markup 


Returns: 


void 


6.28.3.54 void gtk_label_set_use_underline (GtkLabel * label, gboolean setting) 


If true, an underline in the text indicates the next character should be used for the mnemonic accelerator 
key. 


Parameters: 
label [in] a GtkLabel 


setting [in] TRUE if underlines in the text indicate mnemonics 


Returns: 


void 


6.28.3.55 void gtk_label_set_width_chars (GtkLabel + label, gint n_chars) 


Sets the desired width in characters of label to n_chars. 
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Parameters: 


label [in] a GtkLabel 


n_chars [in] the new desired width, in characters. 


Returns: 


void 
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6.29 GtkProgressBar 


6.29.1 Detailed Description 


GtkProgressBar is a widget which indicates progress visually. 


aProgressbar 


Progressbar Sample 


Figure 6.5: GtkProgressBar 


The GtkProgressBar is typically used to display the progress of a long running operation. It provides a vi- 
sual clue that processing is underway. The GtkProgressBar can be used in two different modes: percentage 
mode and activity mode. 


When an application can determine how much work needs to take place (e.g. read a fixed number of 
bytes from a file) and can monitor its progress, it can use the GtkProgressBar in percentage mode and the 
user sees a growing bar indicating the percentage of the work that has been completed. In this mode, the 
application is required to call gtk_progress_bar_set_fraction() periodically to update the progress bar. 


When an application has no accurate way of knowing the amount of work to do, it can use the GtkProgress- 
Bar in activity mode, which shows activity by a block moving back and forth within the progress area. In 
this mode, the application is required to call gtk_progress_bar_pulse() perodically to update the progress 
bar. 


There is quite a bit of flexibility provided to control the appearance of the GtkProgressBar. Functions are 
provided to control the orientation of the bar, optional text can be displayed along with the bar, and the step 
size used in activity mode can be set. 


Code Example 


GtkWidget *progress_bar; 
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progress_bar = gtk_progress_bar_new (); 
gtk_container_add (GTK_CONTAINER (window), progress_bar); 
gtk_widget_show (progress_bar); 


switch (gtk_progress_bar_get_orientation (GTK_PROGRESS_BAR (progress_bar) 
{ 
case GTK_PROGRESS_LEFT_TO_RIGHT: 

gtk_progress_bar_set_orientation (GTK_PROGRESS_BAR (progress_bar), 


GTK_PROGRESS_RIGHT_TO_LEFT) ; 
break; 


case GTK_PROGRESS_RIGHT_TO_LEFT: 
gtk_progress_bar_set_orientation (GTK_PROGRESS_BAR (progress_bar), 
GTK_PROGRESS_LEFT_TO_RIGHT) ; 


break; 


default: 
} 


Data Structures 


e struct _GtkProgress 


GtkProgress stucture. 


e struct _GtkProgressClass 


GtkProgress class stucture. 


e struct _GtkProgressBar 


GtkProgressBar instance stucture. 


e struct _GtkProgressBarClass 


GtkProgressBar instance Class structure. 


Enumerations 


e enum GtkProgressBarStyle 
GtkProgressBar mode. 


e enum GtkProgressBarOrientation 


GtkProgressBar direction. 


Functions 


e GType gtk_progress_bar_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


e GtkWidget * gtk_progress_bar_new (void) 


Creates a new GtkProgressBar. 


e void gtk_progress_bar_pulse (GtkProgressBar *pbar) 
GtkProgress/GtkProgressBar had serious problems in GTK 1.2. 
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e void gtk_progress_bar_set_text (GtkProgressBar *pbar, const gchar xtext) 


Causes the given text to appear superimposed on the progress bar. 


e void gtk_progress_bar_set_fraction (GtkProgressBar *pbar, gdouble fraction) 


Causes the progress bar to "fill in" the given fraction of the bar. 


e void gtk_progress_bar_set_pulse_step (GtkProgressBar *pbar, gdouble fraction) 


Sets the fraction of total progress bar length to move the bouncing block for each call to gtk_progress_bar_- 
pulse(). 


e void gtk_progress_bar_set_orientation (GtkProgressBar *pbar, GtkProgressBarOrientation orienta- 
tion) 


Causes the progress bar to switch to a different orientation (left-to-right, right-to-left, top-to-bottom, or 
bottom-to-top). 


e G_CONST_RETURN gchar x gtk_progress_bar_get_text (GtkProgressBar *pbar) 


Retrieves the text displayed superimposed on the progress bar, if any, otherwise NULL. 


e gdouble gtk_progress_bar_get_fraction (GtkProgressBar *pbar) 


Returns the current fraction of the task that’s been completed. 


e gdouble gtk_progress_bar_get_pulse_step (GtkProgressBar «pbar) 


Retrieves the pulse step set with gtk_progress_bar_set_pulse_step(). 


e GtkProgressBarOrientation gtk_progress_bar_get_orientation (GtkProgressBar *pbar) 


Retrieves the current progress bar orientation. 


e void gtk_progress_bar_set_ellipsize (GtkProgressBar «pbar, PangoEllipsizeMode mode) 


" 


Sets the mode used to ellipsize (add an ellipsis: "...") the text if there is not enough space to render the entire 
string. 


e PangoEllipsizeMode gtk_progress_bar_get_ellipsize (GtkProgressBar *pbar) 


Returns the ellipsizing position of the progressbar. 


6.29.2 Enumeration Type Documentation 
6.29.2.1 enum GtkProgressBarOrientation 


GtkProgressBar direction. 


6.29.2.2 enum GtkProgressBarStyle 


GtkProgressBar mode. 
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6.29.3 Function Documentation 
6.29.3.1 PangoEllipsizeMode gtk_progress_bar_get_ellipsize (GtkProgressBar x pbar) 


Returns the ellipsizing position of the progressbar. 


See gtk_progress_bar_set_ellipsize(). 


Parameters: 


pbar [in] a GtkProgressBar 


Returns: 


PangoEllipsizeMode 


6.29.3.2 gdouble gtk_progress_bar_get_fraction (GtkProgressBar + pbar) 


Returns the current fraction of the task that’s been completed. 


Parameters: 


pbar [in] a GtkProgressBar 


Returns: 


a fraction from 0.0 to 1.0 


6.29.3.3 GtkProgressBarOrientation gtk_progress_bar_get_orientation (GtkProgressBar « pbar) 


Retrieves the current progress bar orientation. 


Parameters: 


pbar [in] a GtkProgressBar 


Returns: 


orientation of the progress bar 


6.29.3.4 gdouble gtk_progress_bar_get_pulse_step (GtkProgressBar x pbar) 


Retrieves the pulse step set with gtk_progress_bar_set_pulse_step(). 


Parameters: 


pbar [in] a GtkProgressBar 


Returns: 


a fraction from 0.0 to 1.0 
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6.29.3.5  G_CONST_RETURN gchar gtk_progress_bar_get_text (GtkProgressBar « pbar) 


Retrieves the text displayed superimposed on the progress bar, if any, otherwise NULL. 


The return value is a reference to the text, not a copy of it, so will become invalid if you change the text in 
the progress bar. 


Parameters: 


pbar [in] a GtkProgressBar 


Returns: 


reference to the text, not a copy of it. 


Remarks: 


The return value is a reference to the text, not a copy of it, so will become invalid if you change the 
text in the progress bar. 


6.29.3.6 GType gtk_progress_bar_get_type (void) 
This Fuction returns GType. 


Returns: 


GType Type 


6.29.3.7 GtkWidget» gtk_progress_bar_new (void) 
Creates a new GtkProgressBar. 


Returns: 


a new GtkProgressBar 


6.29.3.8 void gtk_progress_bar_pulse (GtkProgressBar x pbar) 


GtkProgress/GtkProgressBar had serious problems in GTK 1.2. 


Only 3 or 4 functions are really needed for 95% of progress interfaces; GtkProgress[Bar] had about 
25 functions, and didn’t even include these 3 or 4. 


In activity mode, the API involves setting the adjustment to any random value, just to have the side 
effect of calling the progress bar update function - the adjustment is totally ignored in activity mode 


You set the activity step as a pixel value, which means to set the activity step you basically need to 
connect to size_allocate 


There are ctree_set_expander_style()-functions, to randomly change look-and-feel for no good rea- 
son 


The split between GtkProgress and GtkProgressBar makes no sense to me whatsoever. 
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This was a big wart on GTK and made people waste lots of time, both learning and using the interface. 


So, I have added what I feel is the correct API, and marked all the rest deprecated. However, the changes 
are 100% backward-compatible and should break no existing code. 


The following 9 functions are the new programming interface. Indicates that some progress is made, but 
you don’t know how much. Causes the progress bar to enter "activity mode," where a block bounces back 
and forth. Each call to gtk_progress_bar_pulse() causes the block to move by a little bit (the amount of 
movement per pulse is determined by gtk_progress_bar_set_pulse_step()). 


Parameters: 


pbar [in] a GtkProgressBar 


Returns: 


void 


6.29.3.9 void gtk_progress_bar_set_ellipsize (GtkProgressBar « pbar, PangoEllipsizeMode mode) 


" 


Sets the mode used to ellipsize (add an ellipsis: 
entire string. 


...') the text if there is not enough space to render the 


Parameters: 
pbar [in] a GtkProgressBar 
mode [in] a PangoEllipsizeMode 


Returns: 


void 


6.29.3.10 void gtk_progress_bar_set_fraction (GtkProgressBar « pbar, gdouble fraction) 
Causes the progress bar to "fill in" the given fraction of the bar. 


Parameters: 
pbar [in] a GtkProgressBar 
fraction [in] fraction of the task that’s been completed. fraction should be between 0.0 and 1.0, 
inclusive. 
Returns: 


void 


6.29.3.11 void gtk_progress_bar_set_orientation (GtkProgressBar x pbar, 
GtkProgressBar Orientation orientation) 


Causes the progress bar to switch to a different orientation (left-to-right, right-to-left, top-to-bottom, or 
bottom-to-top). 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.29 GtkProgressBar 307 


Parameters: 


pbar [in] a GtkProgressBar 


orientation [in] orientation of the progress bar 


Returns: 


void 


6.29.3.12 void gtk_progress_bar_set_pulse_step (GtkProgressBar x pbar, gdouble fraction) 


Sets the fraction of total progress bar length to move the bouncing block for each call to gtk_progress_- 
bar_pulse(). 


Parameters: 


pbar [in] a GtkProgressBar 


fraction [in] fraction between 0.0 and 1.0 


Returns: 


void 


6.29.3.13 void gtk_progress_bar_set_text (GtkProgressBar x pbar, const gchar = text) 
Causes the given text to appear superimposed on the progress bar. 


Parameters: 
pbar [in] a GtkProgressBar 
text [in] a UTF-8 string, or NULL 


Returns: 


void 
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6.30 Buttons and Toggles 


Modules 


¢ GtkButton 


The GtkButton widget is generally used to attach a function to that is called when the button is pressed. 


GtkCheckButton 
A GtkCheckButton places a discrete GtkToggleButton next to a widget, (usually a GtkLabel). 


GtkRadioButton 


A single radio button performs the same basic function as a GtkCheckButton, as its position in the object 
hierarchy reflects. 


GtkToggleButton 


A GtkToggleButton is a GtkButton which will remain ’pressed-in’ when clicked. 
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6.31 GtkButton 


6.31.1 Detailed Description 


The GtkButton widget is generally used to attach a function to that is called when the button is pressed. 


The various signals and how to use them are outlined below. The GtkButton widget can hold any valid 
child widget. That is it can hold most any other standard GtkWidget. The most commonly used child is the 


GtkLabel. 


Figure 6.6: GtkButton 


GtkWidget «button; 
GtkWidget xbox; 
button = gtk_button_new (); 


g_signal_connect (G_OBJECT (button), "clicked", 
G_CALLBACK (callback), (gpointer) "cool button"); 
box = xpm_label_box ("info.xpm", "cool button"); 


gtk_widget_show (box); 
gtk_container_add (GTK_CONTAINER (button), box); 
gtk_widget_show (button); 


Data Structures 


e struct _GtkButton 


GtkButton interface structure. 


e struct _GtkButtonClass 


GtkButton interface class structure. 


Functions 


e GType gtk_button_get_type (void) G_LGNUC_CONST 


This Fuction returns GType. 


e GtkWidget x gtk_button_new (void) 


Creates a new GtkButton widget. 


e GtkWidget * gtk_button_new_with_label (const gchar *label) 


Creates a GtkButton widget with a GtkLabel child containing the given text. 


e GtkWidget * gtk_button_new_from_stock (const gchar *stock_id) 
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Creates a new GtkButton containing the image and text from a stock item. 


e GtkWidget * gtk_button_new_with_mnemonic (const gchar xlabel) 


[Deprecated] Creates a new GtkButton containing a label. 


e void gtk_button_pressed (GtkButton x*button) 
Emits a GtkButton: :pressed signal to the given GtkButton. 


e void gtk_button_released (GtkButton *button) 


Emits a GtkButton::released signal to the given GtkButton. 


e void gtk_button_clicked (GtkButton *button) 
Emits a GtkButton::clicked signal to the given GtkButton. 


e void gtk_button_enter (GtkButton *button) 


Emits a GtkButton::enter signal to the given GtkButton. 


e void gtk_button_leave (GtkButton *button) 


Emits a GtkButton::leave signal to the given GtkButton. 


e void gtk_button_set_relief (GtkButton «button, GtkReliefStyle newstyle) 
Sets the relief style of the edges of the given GtkButton widget. 


e GtkReliefStyle gtk_button_get_relief (GtkButton *button) 


Returns the current relief style of the given GtkButton. 


e void gtk_button_set_label (GtkButton «button, const gchar *label) 


Sets the text of the label of the button to str. 


e G_CONST_RETURN gchar * gtk_button_get_label (GtkButton *button) 
Fetches the text from the label of the button, as set by gtk_button_set_label(). 


e void gtk_button_set_use_underline (GtkButton «button, gboolean use_underline) 


If true, an underline in the text of the button label indicates the next character should be used for the 
mnemonic accelerator key. 


e gboolean gtk_button_get_use_underline (GtkButton x*button) 


Returns whether an embedded underline in the button label indicates a mnemonic. 


e void gtk_button_set_use_stock (GtkButton «button, gboolean use_stock) 


If true, the label set on the button is used as a stock id to select the stock item for the button. 


e gboolean gtk_button_get_use_stock (GtkButton *button) 


Returns whether the button label is a stock item. 


e void gtk_button_set_focus_on_click (GtkButton *button, gboolean focus_on_click) 


Sets whether the button will grab focus when it is clicked with the mouse. 


e gboolean gtk_button_get_focus_on_click (GtkButton button) 


Returns whether the button grabs focus when it is clicked with the mouse. 
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e void gtk_button_set_alignment (GtkButton «button, gfloat xalign, gfloat yalign) 


Sets the alignment of the child. 


e void gtk_button_get_alignment (GtkButton *button, gfloat *xalign, gfloat *yalign) 


Gets the alignment of the child in the button. 


e void gtk_button_set_image (GtkButton «button, GtkWidget *image) 


Set the image of button to the given widget. 


e GtkWidget x gtk_button_get_image (GtkButton *button) 


Gets the widget that is currenty set as the image of button. 


e void gtk_button_set_image_position (GtkButton «button, GtkPositionType position 
g ge_p ype p 


Sets the position of the image relative to the text inside the button. 


e GtkPositionType gtk_button_get_image_position (GtkButton button) 


Gets the position of the image relative to the text inside the button. 


6.31.2 Function Documentation 
6.31.2.1 void gtk_button_clicked (GtkButton * button) 


Emits a GtkButton::clicked signal to the given GtkButton. 


Parameters: 


button [in] The GtkButton you want to send the signal to. 


Returns: 


void 


6.31.2.2 void gtk_button_enter (GtkButton x button) 


Emits a GtkButton::enter signal to the given GtkButton. 


Parameters: 


button [in] The GtkButton you want to send the signal to. 


Returns: 


void 
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6.31.2.3 void gtk_button_get_alignment (GtkButton x button, gfloat x xalign, gfloat x yalign) 
Gets the alignment of the child in the button. 


Parameters: 


button [in] a GtkButton 
xalign [out] return location for horizontal alignment 


yalign [out] return location for horizontal alignment 


Returns: 


void 


6.31.2.4 gboolean gtk_button_get_focus_on_click (GtkButton * button) 


Returns whether the button grabs focus when it is clicked with the mouse. 


See gtk_button_set_focus_on_click(). 


Parameters: 


button [in] a GtkButton 


Returns: 


TRUE if the button grabs focus when it is clicked with the mouse. 


6.31.2.5 GtkWidget* gtk_button_get_image (GtkButton « button) 


Gets the widget that is currenty set as the image of button. 


This may have been explicitly set by gtk_button_set_image() or constructed by gtk_button_new_from_- 
stock(). 


Parameters: 


button [in] a GtkButton 


Returns: 


a GtkWidget or NULL in case there is no image 


6.31.2.6 GtkPositionType gtk_button_get_image_position (GtkButton * button) 


Gets the position of the image relative to the text inside the button. 


Parameters: 


button [in] a GtkButton 


Returns: 


the position 
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6.31.2.7 G_CONST_RETURN gchar» gtk_button_get_label (GtkButton x button) 


Fetches the text from the label of the button, as set by gtk_button_set_label(). 


Tf the label text has not been set the return value will be NULL. This will be the case 1f you create an empty 
button with gtk_button_new() to use as a container. 


Parameters: 


button [in] The GtkButton you want to set relief styles of. 


Returns: 


The text of the label widget. This string is owned by the widget and must not be modified or freed. 


6.31.2.8 GtkReliefStyle gtk_button_get_relief (GtkButton x button) 
Returns the current relief style of the given GtkButton. 


Parameters: 


button [in] The GtkButton you want the GtkReliefStyle from. 


Returns: 


The current GtkReliefStyle 


6.31.2.9 GType gtk_button_get_type (void) 
This Fuction returns GType. 


Returns: 


GType Type 


6.31.2.10 gboolean gtk_button_get_use_stock (GtkButton * button) 


Returns whether the button label is a stock item. 


Parameters: 


button [in] a GtkButton 


Returns: 


TRUE if the button label is used to select a stock item instead of being used directly as the label text. 


6.31.2.11 gboolean gtk_button_get_use_underline (GtkButton x button) 


Returns whether an embedded underline in the button label indicates a mnemonic. 


See gtk_button_set_use_underline(). 
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Parameters: 


button [in] a GtkButton 


Returns: 


TRUE if an embedded underline in the button label indicates the mnemonic accelerator keys. 


6.31.2.12 void gtk_button_leave (GtkButton x button) 


Emits a GtkButton::leave signal to the given GtkButton. 


Parameters: 


button [in] The GtkButton you want to send the signal to. 


Returns: 


void 


6.31.2.13 GtkWidget» gtk_button_new (void) 


Creates a new GtkButton widget. 


To add a child widget to the button, use gtk_container_add(). 


Returns: 


The newly created GtkButton widget. 


6.31.2.14 GtkWidget« gtk_button_new_from_stock (const gchar « stock_id) 


Creates a new GtkButton containing the image and text from a stock item. 


Some stock ids have preprocessor macros like GTK_STOCK_OK and GTK_STOCK_APPLY. If stock_id 
is unknown, then it will be treated as a mnemonic label (as for gtk_button_new_with_mnemonic()). 


Parameters: 


stock_id [in] the name of the stock item 


Returns: 


a new GtkButton 


6.31.2.15 GtkWidgetx gtk_button_new_with_label (const gchar x label) 


Creates a GtkButton widget with a GtkLabel child containing the given text. 


Parameters: 


label [in] The text you want the GtkLabel to hold. 


Returns: 


a new GtkButton 
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6.31.2.16 GtkWidget« gtk_button_new_with_mnemonic (const gchar + label) 


[Deprecated] Creates a new GtkButton containing a label. 


If characters in label are preceded by an underscore, they are underlined. If you need a literal underscore 
character in a label, use *__” (two underscores). The first underlined character represents a keyboard 
accelerator called a mnemonic. Pressing Alt and that key activates the button. 


Parameters: 


label [in] The text of the button, with an underscore in front of the mnemonic character 


Returns: 


a new GtkButton 


Deprecated 
LIMO R1 


6.31.2.17 void gtk_button_pressed (GtkButton x button) 
Emits a GtkButton::pressed signal to the given GtkButton. 


Parameters: 


button [in] The GtkButton you want to send the signal to. 


Returns: 


void 


6.31.2.18 void gtk_button_released (GtkButton x button) 


Emits a GtkButton::released signal to the given GtkButton. 


Parameters: 


button [in] The GtkButton you want to send the signal to. 


Returns: 


void 


6.31.2.19 void gtk_button_set_alignment (GtkButton « button, gfloat xalign, gfloat yalign) 


Sets the alignment of the child. 


This property has no effect unless the child is a GtkMisc or a GtkAligment. 


Parameters: 


button [in] a GtkButton 
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xalign [in] the horizontal position of the child, 0.0 is left aligned, 1.0 is right aligned 
yalign [in] the vertical position of the child, 0.0 is top aligned, 1.0 is bottom aligned 


Returns: 


void 


6.31.2.20 void gtk_button_set_focus_on_click (GtkButton « button, gboolean focus_on_click) 


Sets whether the button will grab focus when it is clicked with the mouse. 

Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard 
focus removed from the main area of the application. 

Parameters: 


button [in] a GtkButton 


focus_on_click [in] whether the button grabs focus when clicked with the mouse 


Returns: 


void 


6.31.2.21 void gtk_button_set_image (GtkButton « button, GtkWidget x image) 


Set the image of button to the given widget. 

Note that it depends on the gtk-button-images setting whether the image will be displayed or not, you don't 
have to call gtk_widget_show() on image yourself. 

Parameters: 


button [in] a GtkButton 


image [in] a widget to set as the image for the button 


Returns: 


void 


6.31.2.22 void gtk_button_set_image position (GtkButton « button, GtkPositionType position) 


Sets the position of the image relative to the text inside the button. 


Parameters: 


button [in] a GtkButton 


position [out] the position 


Returns: 


void 
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6.31.2.23 void gtk_button_set_label (GtkButton « button, const gchar + label) 


Sets the text of the label of the button to str. 
This text is also used to select the stock item if gtk_button_set_use_stock() is used. 
Parameters: 
button [in] a GtkButton 
label [in] a string 
Returns: 


void 


6.31.2.24 void gtk_button_set_relief (GtkButton x button, GtkReliefStyle newstyle) 


Sets the relief style of the edges of the given GtkButton widget. 


Three styles exist, GTK_RELIEF_NORMAL, GTK_RELIEF_HALE GTK_RELIEF_NONE. The default 
style is, as one can guess, GTK_RELIEF_NORMAL. 


Parameters: 


button [in] The GtkButton you want to set relief styles of. 
newstyle [in] The GtkReliefStyle as described above. 


Returns: 


void 


6.31.2.25 void gtk_button_set_use_stock (GtkButton « button, gboolean use_stock) 


Tf true, the label set on the button is used as a stock id to select the stock item for the button. 


Parameters: 


button [in] a GtkButton 
use_stock [in] TRUE if the button should use a stock item 


Returns: 


void 


6.31.2.26 void gtk_button_set_use_underline (GtkButton « button, gboolean use_underline) 


If true, an underline in the text of the button label indicates the next character should be used for the 
mnemonic accelerator key. 


Parameters: 


button [in] a GtkButton 
use_underline [in] TRUE if underlines in the text indicate mnemonics 


Returns: 


void 
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6.32 GtkCheckButton 


6.32.1 Detailed Description 


A GtkCheckButton places a discrete GtkToggleButton next to a widget, (usually a GtkLabel). 
See the section on GtkToggleButton widgets for more information about toggle/check buttons. 


The important signal (toggled”) is also inherited from GtkToggleButton. 


Bach eck 


[-]itern] 
item 


items 


Figure 6.7: GtkCheckButton 


Data Structures 


e struct _GtkCheckButton 


GtkCheckButton interface structure. 


e struct _GtkCheckButtonClass 


GtkCheckButton interface class structure. 


Functions 


e GType gtk_check_button_get_type (void) G_GNUC_CONST 


This Fuction returns GType. 


e GtkWidget * gtk_check_button_new (void) 


Creates a new GtkCheckButton. 
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e GtkWidget * gtk_check_button_new_with_label (const gchar «label) 


Creates a new GtkCheckButton with a GtkLabel to the right of it. 


e GtkWidget * gtk_check_button_new_with_mnemonic (const gchar *label) 


[Deprecated] Creates a new GtkCheckButton containing a label. 


6.32.2 Function Documentation 


6.32.2.1 GType gtk_check_button_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


6.32.2.2 GtkWidget* gtk_check_button_new (void) 
Creates a new GtkCheckButton. 


Returns: 


a new GtkCheckButton 


6.32.2.3 GtkWidget gtk_check_button_new_with_label (const gchar x label) 


Creates a new GtkCheckButton with a GtkLabel to the right of it. 


Parameters: 


— label : the text for the check button. 


Returns: 


anew GtkCheckButton 


6.32.2.4 GtkWidget gtk_check_button_new_with_mnemonic (const gchar x label) 


[Deprecated] Creates a new GtkCheckButton containing a label. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the check button. 


Parameters: 


— label : The text of the button, with an underscore in front of the mnemonic character 


Returns: 


a new GtkCheckButton 
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Deprecated 
LIMO R1 
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6.33 GtkRadioButton 


6.33.1 Detailed Description 


A single radio button performs the same basic function as a GtkCheckButton, as its position in the object 
hierarchy reflects. 


It is only when multiple radio buttons are grouped together that they become a different user interface 
component in their own right. 


Every radio button is a member of some group of radio buttons. When one is selected, all other radio 
buttons in the same group are deselected. A GtkRadioButton is one way of giving the user a choice from 
many options. 


Radio button widgets are created with gtk_radio_button_new(), passing NULL as the argument if this is the 
first radio button in a group. In subsequent calls, the group you wish to add this button to should be passed 
as an argument. Optionally, gtk_radio_button_new_with_label() can be used if you want a text label on the 
radio button. 


Alternatively, when adding widgets to an existing group of radio buttons, use gtk_radio_button_new_- 
from_widget() with a GtkRadioButton that already has a group assigned to it. The convenience function 
gtk_radio_button_new_with_label_from_widget() is also provided. 


To retrieve the group a GtkRadioButton is assigned to, use gtk_radio_button_get_group(). 


To remove a GtkRadioButton from one group and make it part of a new one, use gtk_radio_button_set_- 
group(). 


The group list does not need to be freed, as each GtkRadioButton will remove itself and its list item when 
it is destroyed. 


Figure 6.8: GtkRadioButton 
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Code Example: 


// How to create a group of two radio buttons. 
xvoid create_radio_buttons (void) { 


GtkWidget *window, *radiol, *radio2, *box, x*entry; 
window = gtk_window_new (GTK_WINDOW_TOPLEVEL) ; 
box = gtk_vbox_new (TRUE, 2); 


// Create a radio button with a GtkEntry widget 
radiol = gtk_radio_button_new (NULL); 

entry = gtk_entry_new (); 

gtk_container_add (GTK_CONTAINER (radiol), entry); 


// Create a radio button with a label 
radio2 = gtk_radio_button_new_with_label_from_widget (GTK_RADIO_BUTTON (radiol), 
"I’m the second radio button."); 


// Pack them into a box, then show all the widgets 
gtk_box_pack_start (GTK_BOX (box), radiol, TRUE, TRUE, 2); 
gtk_box_pack_start (GTK_BOX (box), radio2, TRUE, TRUE, 2); 
gtk_container_add (GTK_CONTAINER (window), box); 
gtk_widget_show_all (window) ; 
return; 


Data Structures 


e struct _GtkRadioButton 


GtkRadioButton interface structure. 


e struct _GtkRadioButtonClass 


GtkRadioButton interface class structure. 


Functions 


e GType gtk_radio_button_get_type (void) G_GNUC_CONST 


This Fuction returns GType. 


e GtkWidget * gtk_radio_button_new (GSList *group) 


Creates a new GtkRadioButton. 


GtkWidget * gtk_radio_button_new_from_widget (GtkRadioButton *group) 


Creates a new GtkRadioButton, adding it to the same group as group.As with gtk_radio_button_new(), a 
widget should be packed into the radio button. 


e GtkWidget * gtk_radio_button_new_with_label (GSList «group, const gchar label) 


Creates a new GtkRadioButton with a text label. 


GtkWidget * gtk_radio_button_new_with_label_from_widget (GtkRadioButton «group, const gchar 
*label) 


Creates a new GtkRadioButton with a text label, adding it to the same group as group. 


GtkWidget * gtk_radio_button_new_with_mnemonic (GSList «group, const gchar xlabel) 
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[Deprecated] Creates a new GtkRadioButton containing a label, adding it to the same group as group. 


e GtkWidget * gtk_radio_button_new_with_mnemonic_from_widget (GtkRadioButton «group, const 
gchar *label) 


[Deprecated] Creates a new GtkRadioButton containing a label. 


e GSList * gtk_radio_button_get_group (GtkRadioButton *radio_button) 


Retrieves the group assigned to a radio button. 


e void gtk_radio_button_set_group (GtkRadioButton *radio_button, GSList *group) 


Sets a GtkRadioButton’s group. 


6.33.2 Function Documentation 


6.33.2.1 GSList« gtk_radio_button_get_group (GtkRadioButton « radio_button) 


Retrieves the group assigned to a radio button. 


Parameters: 


— group : a GtkRadioButton. 


Returns: 


a linked list containing all the radio buttons in the same group as radio_button. 


6.33.2.2 GType gtk_radio_button_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


6.33.2.3 GtkWidget* gtk_radio_button_new (GSList « group) 


Creates a new GtkRadioButton. 


To be of any practical value, a widget should then be packed into the radio button. 


Parameters: 


— group : an existing radio button group, or NULL if you are creating a new group. 


Returns: 


a new radio button. 
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6.33.2.4 GtkWidget* gtk_radio_button_new_from_widget (GtkRadioButton * group) 


Creates a new GtkRadioButton, adding it to the same group as group.As with gtk_radio_button_new(), a 
widget should be packed into the radio button. 


Parameters: 


— group : an existing GtkRadioButton. 


Returns: 


a new radio button. 


6.33.2.5 GtkWidget» gtk_radio_button_new_with_label (GSList x group, const gchar x label) 


Creates a new GtkRadioButton with a text label. 


Parameters: 
— group : an existing radio button group, or NULL if you are creating a new group. 


— label : the text label to display next to the radio button. 


Returns: 


a new radio button. 


6.33.2.6 GtkWidget» gtk_radio_button_new_with_label_from_widget (GtkRadioButton * group, 
const gchar + label) 


Creates a new GtkRadioButton with a text label, adding it to the same group as group. 


Parameters: 
— group : an existing GtkRadioButton. 


— label : a text string to display next to the radio button. 


Returns: 


a new radio button. 


6.33.2.7 GtkWidgetx gtk_radio_button_new_with_mnemonic (GSList « group, const gchar * label) 


[Deprecated] Creates a new GtkRadioButton containing a label, adding it to the same group as group. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the button. 


Parameters: 
— group : the radio button group 


+ label : the text of the button, with an underscore in front of the mnemonic character 
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Returns: 


a new radio button. 


Deprecated 
LIMO R1 


6.33.2.8 GtkWidget* gtk_radio_button_new_with_mnemonic_from_widget (GtkRadioButton x 
group, const gchar + label) 


[Deprecated] Creates a new GtkRadioButton containing a label. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the button. 


Parameters: 
— group : widget to get radio group from 
— label : the text of the button, with an underscore in front of the mnemonic character 


Returns: 


a new GtkRadioButton 


Deprecated 
LIMO R1 


6.33.2.9 void gtk_radio_button_set_group (GtkRadioButton x radio_button, GSList x group) 


Sets a GtkRadioButton’s group. 

It should be noted that this does not change the layout of your interface in any way, so 1f you are changing 
the group, it is likely you will need to re-arrange the user interface to reflect these changes. 

Parameters: 


— radio_button : a GtkRadioButton. 


— group : an existing radio button group, such as one returned from gtk_radio_button_get_group(). 


Returns: 


void 
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6.34 GtkToggleButton 


6.34.1 Detailed Description 


A GtkToggleButton is a GtkButton which will remain ’pressed-in’ when clicked. 
Clicking again will cause the toggle button to return to its normal state. 


A toggle button is created by calling either gtk_toggle_button_new() or gtk_toggle_button_new_with_- 
label(). If using the former, it is advisable to pack a widget, (such as a GtkLabel and/or a GtkPixmap), into 
the toggle button”s container. (See GtkButton for more information). 


The state of a GtkToggleButton can be set specifically using gtk_toggle_button_set_active(), and retrieved 
using gtk_toggle_button_get_active(). 


To simply switch the state of a toggle button, use gtk_toggle_button_toggled. 


Toggle Button 


Figure 6.9: GtkToggleButton 


Code Example: 


<b>Creating two GtkToggleButton widgets </b> 


void make_toggles (void) { 
GtkWidget *dialog, *togglel, *toggle2; 


dialog = gtk_dialog_new (); 
togglel = gtk_toggle_button_new_with_label ("Hi, i'm a toggle button."); 


// Makes this toggle button invisible 
gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (togglel), TRUE); 


g_signal_connect (togglel, "toggled", 
G_CALLBACK (output_state), NULL); 
gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area), 
togglel, FALSE, FALSE, 2); 


toggle2 = gtk_toggle_button_new_with_label ("Hi, i'm another toggle button."); 

gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (toggle2), FALSE); 

g_signal_connect (toggle2, "toggled", 

G_CALLBACK (output_state), NULL); 

gtk_box_pack_start (GTK_BOX (GTK_DIALOG (dialog)->action_area), 
toggle2, FALSE, FALSE, 2); 


gtk_widget_show_all (dialog); 
} 


Data Structures 


e struct _GtkToggleButton 
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GtkToggleButton interface structure. 


e struct _GtkToggleButtonClass 


GtkToggleButton interface class structure. 


Functions 


e GType gtk_toggle_button_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


e GtkWidget * gtk_toggle_button_new (void) 


Creates a new toggle button. 


e GtkWidget x gtk_toggle_button_new_with_label (const gchar «label) 


Creates a new toggle button with a text label. 


e GtkWidget x gtk_toggle_button_new_with_mnemonic (const gchar xlabel) 


[Deprecated] Creates a new GtkToggleButton containing a label. 


e void gtk_toggle_button_set_mode (GtkToggleButton «toggle button, gboolean draw_indicator) 


Sets whether the button is displayed as a separate indicator and label. 


e gboolean gtk_toggle_button_get_mode (GtkToggleButton *toggle_button) 


Retrieves whether the button is displayed as a separate indicator and label. 


e void gtk_toggle_button_set_active (GtkToggleButton *toggle_button, gboolean is_active) 


Sets the status of the toggle button. 


e gboolean gtk_toggle_button_get_active (GtkToggleButton *toggle_button) 


Queries a GtkToggleButton and returns its current state. 


e void gtk_toggle_button_toggled (GtkToggleButton *toggle_button) 
Emits the toggled signal on the GtkToggleButton. 


e void gtk_toggle_button_set_inconsistent (GtkToggleButton *toggle_button, gboolean setting) 


If the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a 
toggle button, and the current values in that range are inconsistent, you may want to display the toggle in 
an "in between" state. 


e gboolean gtk_toggle_button_get_inconsistent (GtkToggleButton *toggle_button) 


Gets the value set by gtk_toggle_button_set_inconsistent(). 


6.34.2 Function Documentation 


6.34.2.1 gboolean gtk_toggle_button_get_active (GtkToggleButton x toggle_button) 


Queries a GtkToggleButton and returns its current state. 


Returns TRUE if the toggle button is pressed in and FALSE if it is raised. 
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Parameters: 


— toggle_button : a GtkToggleButton 


Returns: 


a gboolean value. 


6.34.2.2 gboolean gtk_toggle button_get_inconsistent (GtkToggleButton « toggle_button) 


Gets the value set by gtk_toggle_button_set_inconsistent(). 


Parameters: 


— toggle_button : a GtkToggleButton 


Returns: 


TRUE if the button is displayed as inconsistent, FALSE otherwise 


6.34.2.3 gboolean gtk_toggle button_get_mode (GtkToggleButton x toggle_button) 


Retrieves whether the button is displayed as a separate indicator and label. 


See gtk_toggle_button_set_mode(). 


Parameters: 


— toggle_button : a GtkToggleButton 


Returns: 


TRUE if the togglebutton is drawn as a separate indicator and label. 


6.34.2.4 GType gtk_toggle_button_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


6.34.2.5  GtkWidget* gtk_toggle_button_new (void) 


Creates a new toggle button. 


A widget should be packed into the button, as in gtk_button_new(). 


Returns: 


a new toggle button. 
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6.34.2.6 GtkWidget* gtk_toggle_button_new_with_label (const gchar + label) 


Creates a new toggle button with a text label. 


Parameters: 


— label : a string containing the message to be placed in the toggle button. 


Returns: 


a new toggle button. 


6.34.2.7 GtkWidget* gtk_toggle_button_new_with_mnemonic (const gchar x label) 


[Deprecated] Creates a new GtkToggleButton containing a label. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the button. 


Parameters: 


— label : the text of the button, with an underscore in front of the mnemonic character 


Returns: 


a new toggle button. 


Deprecated 
LIMO R1 


6.34.2.8 void gtk_toggle_button_set_active (GtkToggleButton * toggle_button, gboolean is_active) 


Sets the status of the toggle button. 

Set to TRUE if you want the GtkToggleButton to be ’pressed in’, and FALSE to raise it. This action causes 
the toggled signal to be emitted. 

Parameters: 


<— toggle_button : a GtkToggleButton 
< is_active : TRUE or FALSE. 


Returns: 


void 


6.34.2.9 void gtk_toggle_button_set_inconsistent (GtkToggleButton x toggle_button, gboolean 
setting) 


If the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a 
toggle button, and the current values in that range are inconsistent, you may want to display the toggle in 
an "in between" state. 
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This function turns on "in between" display. Normally you would turn off the inconsistent state again if the 
user toggles the toggle button. This has to be done manually, gtk_toggle_button_set_inconsistent() only 
affects visual appearance, it doesn’t affect the semantics of the button. 


Parameters: 


— toggle_button : a GtkToggleButton 


— setting : TRUE if state is inconsistent 


Returns: 


void 


6.34.2.10 void gtk_toggle button_set_mode (GtkToggleButton > toggle_button, gboolean 
draw_indicator) 


Sets whether the button is displayed as a separate indicator and label. 


You can call this function on a checkbutton or a radiobutton with draw_indicator = FALSE to make the 
button look like a normal button 


This function only affects instances of classes like GtkCheckButton and GtkRadioButton that derive from 
GtkToggleButton, not instances of GtkToggleButton itself. 
Parameters: 


<— toggle_button : a GtkToggleButton 


— draw_indicator : if TRUE, draw the button as a separate indicator and label; if FALSE, draw the 
button like a normal button 


Returns: 


void 


6.34.2.11 void gtk_toggle_button_toggled (GtkToggleButton « toggle_button) 


Emits the toggled signal on the GtkToggleButton. 


There is no good reason for an application ever to call this function. 


Parameters: 


— toggle_button : a GtkToggleButton. 


Returns: 


void 
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6.35 Numeric / Text Data Entry 


Modules 


e GtkEntry 
The GtkEntry widget is a single line text entry widget. 


e GtkEntryCompletion 


GtkEntryCompletion is an auxiliary object to be used in conjunction with GtkEntry to provide the completion 
functionality. 


GtkHScale 
This file defines the functions of GtkHScale. 


GtkVScale 


The GtkVScale widget is used to allow the user to select a value using a vertical slider. 


GtkEditable 


The GtkEditable interface is an interface which should be implemented by text editing widgets, such as 
GtkEntry and GtkText. 
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6.36 GtkEntry 


6.36.1 Detailed Description 


The GtkEntry widget is a single line text entry widget. 


A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation 
of the widget, the widget will scroll so that the cursor position is visible. 


This widget is modified for Mobile environment with enhancement to in IM context support. 


<disabled= 


Figure 6.10: GtkEntry 


Modified for 
LIMO RI 


Code Example 


GtkWidget xentry; 

GtkWidget *vbox; 

gint tmp_pos; 

vbox = gtk_vbox_new (FALSE, 0); 

gtk_container_add (GTK_CONTAINER (window), vbox); 
gtk_widget_show (vbox); 

// create entry 

entry = gtk_entry_new (); 

gtk_entry_set_max_length (GTK_ENTRY (entry), 50); 
g_signal_connect (G_OBJECT (entry), "activate", 
G_CALLBACK (enter_callback), 
(gpointer) entry); 
gtk_entry_set_text (GTK_ENTRY (entry), "hello"); 
tmp_pos = GTK_ENTRY (entry)->text_length; 
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gtk_editable_insert_text (GTK_EDITABLE (entry), " world", -1, £tmp_pos); 
gtk_editable_select_region (GTK_EDITABLE (entry), 0, GTK_ENTRY (entry)->text_length); 
gtk_box_pack_start (GTK_BOX (vbox), entry, TRUE, TRUE, 0); 

gtk_widget_show (entry); 


Data Structures 


e struct _GtkEntry 


GtkEntry instance structure. 


e struct _GtkEntryClass 


GTK Native GtkEntry instance class structure. 


Enumerations 


e enum GtkEntryNavigationMode { GTK_ENTRY_MODE_ NORMAL, GTK_ENTRY_MODE _- 
SELECTION } 


Functions 


e GtkWidget * gtk_entry_new (void) 


Creates a new entry. 


e void gtk_entry_set_visibility (GtkEntry «entry, gboolean visible) 


Sets whether the contents of the entry are visible or not. 


e gboolean gtk_entry_get_visibility (GtkEntry *entry) 


Retrieves whether the text in entry is visible. 


e void gtk_entry_set_invisible_char (GtkEntry x*entry, gunichar ch) 


Sets the character to use in place of the actual text when gtk_entry_set_visibility() has been called to set text 
visibility to FALSE. 


e gunichar gtk_entry_get_invisible_char (GtkEntry *entry) 


Retrieves the character displayed in place of the real characters for entries with visibility set to false. 


e void gtk_entry_set_has_frame (GtkEntry «entry, gboolean setting) 


Sets whether the entry has a beveled frame around it. 


e gboolean gtk_entry_get_has_frame (GtkEntry *entry) 
Gets the value set by gtk_entry_set_has_frame(). 


e void gtk_entry_set_inner_border (GtkEntry *entry, const GtkBorder «border) 


Sets entry’s inner-border property to border, or clears it if NULL is passed. 


G_CONST_RETURN GtkBorder x gtk_entry_get_inner_border (GtkEntry x*entry) 


This function returns the entry’s inner-border property. 


e void gtk_entry_set_max_length (GtkEntry x*entry, gint max) 
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Sets the maximum allowed length of the contents of the widget. 


gint gtk_entry_get_max_length (GtkEntry xentry) 


Retrieves the maximum allowed length of the text in entry. 


void gtk_entry_set_activates_default (GtkEntry x*entry, gboolean setting) 


If setting is TRUE, pressing Enter in the entry will activate the default widget for the window containing the 
entry. 


gboolean gtk_entry_get_activates_default (GtkEntry xentry) 


Retrieves the value set by gtk_entry_set_activates_default(). 


void gtk_entry_set_width_chars (GtkEntry x*entry, gint n_chars) 


Changes the size request of the entry to be about the right size for n_chars characters. 


gint gtk_entry_get_width_chars (GtkEntry entry) 


Gets the characters size, .i.e. 


void gtk_entry_set_text (GtkEntry *entry, const gchar *text) 


Sets the text in the widget to the given value, replacing the current contents. 


G_CONST_RETURN gchar x gtk_entry_get_text (GtkEntry xentry) 


Retrieves the contents of the entry widget. 


PangoLayout * gtk_entry_get_layout (GtkEntry entry) 
Gets the PangoLayout used to display the entry. 


void gtk_entry_get_layout_offsets (GtkEntry *entry, gint «x, gint *y) 


Obtains the position of the PangoLayout used to render text in the entry, in widget coordinates. 


void gtk_entry_set_alignment (GtkEntry «entry, gfloat xalign) 


Sets the alignment for the contents of the entry. 


gfloat gtk_entry_get_alignment (GtkEntry entry) 


Gets the alignment value of the contents of the entry. 


gint gtk_entry_layout_index_to_text_index (GtkEntry *entry, gint layout_index) 


Converts from a position in the entry contents (returned by gtk_entry_get_text()) to a position in the entry’s 
PangoLayout (returned by gtk_entry_get_layout(), with text retrieved via pango_layout_get_text()). 


gint gtk_entry_text_index_to_layout_index (GtkEntry entry, gint text_index) 


Converts from a position in the entry’s PangoLayout (returned by gtk_entry_get_layout()) to a position in 
the entry contents (returned by gtk_entry_get_text()). 


void gtk_entry_set_prompt_string (GtkEntry xentry, const gchar *text) 


Sets String displayed during the unfocused state and entry is empty. 


G_CONST_RETURN gchar x gtk_entry_get_prompt_string (GtkEntry *entry) 


Returns the string displayed during the unfocused state and entry is empty. 
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e void gtk_entry_set_navigation_mode (GtkEntry entry, GtkEntryNavigationMode mode) 


Sets the Cursor movement mode. 


e GtkEntryNavigationMode gtk_entry_get_navigation_mode (GtkEntry entry) 


Returns the current navigation Mode. 


e guint gtk_entry_get_remaining_input_char_count (GtkEntry xentry) 


Returns the count of remaining more number of chars can be entered/added based on UTF-8 encoding. 


e guint gtk_entry_get_remaining_input_byte_count (GtkEntry xentry) 


Returns the count of remaining more number of bytes are allowed to add. 


e void gtk_entry_set_completion (GtkEntry «entry, GtkEntryCompletion *completion) 


Sets completion to be the auxiliary completion object to use with entry. 


e GtkEntryCompletion * gtk_entry_get_completion (GtkEntry xentry) 


Returns the auxiliary completion object currently in use by entry. 


6.36.2 Enumeration Type Documentation 


6.36.2.1 enum GtkEntryNavigationMode 


Enumerator: 


GTK_ENTRY_MODE_NORMAL Default Navigation mode, Navigation keys moves the cursor. 


GTK_ENTRY_MODE_SELECTION Text Selection mode, Navigation keys selects the text, which 
can Cut/Copy. 


6.36.3 Function Documentation 
6.36.3.1 gboolean gtk_entry_get_activates_default (GtkEntry « entry) 


Retrieves the value set by gtk_entry_set_activates_default(). 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


TRUE if the entry will activate the default widget 


6.36.3.2  gfloat gtk_entry_get_alignment (GtkEntry « entry) 


Gets the alignment value of the contents of the entry. 


i.e. Gets the value set by gtk_entry_set_alignment(). 


Parameters: 


entry [in] a GtkEntry. 
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Returns: 


the alignment 


6.36.3.3 GtkEntryCompletion« gtk_entry_get_completion (GtkEntry x entry) 
Returns the auxiliary completion object currently in use by entry. 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


The auxiliary completion object currently in use by entry. 


6.36.3.4 gboolean gtk_entry_get_has_frame (GtkEntry x entry) 


Gets the value set by gtk_entry_set_has_frame(). 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


whether the entry has a beveled frame 


6.36.3.5  G_CONST_RETURN GtkBorderx gtk_entry_get_inner_border (GtkEntry x entry) 


This function returns the entry’s inner-border property. 


See gtk_entry_set_inner_border() for more information. 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


the entry’s GtkBorder, or NULL if none was set. 


6.36.3.6 gunichar gtk_entry_get_invisible_char (GtkEntry + entry) 
Retrieves the character displayed in place of the real characters for entries with visibility set to false. 
See gtk_entry_set_invisible_char(). 
Parameters: 
entry [in] a GtkEntry. 


Returns: 


the current invisible char, or 0, if the entry does not show invisible text at all. 
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6.36.3.7 PangoLayout* gtk_entry_get_layout (GtkEntry x entry) 


Gets the PangoLayout used to display the entry. 


The layout is useful to e.g. convert text positions to pixel positions, in combination with gtk_entry_get_- 
layout_offsets(). The returned layout is owned by the entry and must not be modified or freed by the 
caller. 


Keep in mind that the layout text may contain a preedit string, so gtk_entry_layout_index_to_text_index() 
and gtk_entry_text_index_to_layout_index() are needed to convert byte indices in the layout to byte indices 
in the entry contents. 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


the PangoLayout for this entry 


6.36.3.8 void gtk_entry_get_layout_offsets (GtkEntry x entry, gint x x, gint x y) 


Obtains the position of the PangoLayout used to render text in the entry, in widget coordinates. 


Useful if you want to line up the text in an entry with some other text, e.g. when using the entry to 
implement editable cells in a sheet widget. 


Also useful to convert mouse events into coordinates inside the PangoLayout, e.g. to take some action if 
some part of the entry text is clicked. 


Note that as the user scrolls around in the entry the offsets will change; you’ll need to connect to the 
"notify::scroll-offset" signal to track this. Remember when using the PangoLayout functions you need to 
convert to and from pixels using PANGO_PIXELS() or PANGO_SCALE. 


Keep in mind that the layout text may contain a preedit string, so gtk_entry_layout_index_to_text_index() 
and gtk_entry_text_index_to_layout_index() are needed to convert byte indices in the layout to byte indices 
in the entry contents. 


Parameters: 


entry [in] a GtkEntry. 
x [out] location to store X offset of layout, or NULL 
y [out] location to store Y offset of layout, or NULL 


Returns: 


void 


6.36.3.9 gint gtk_entry_get_max_length (GtkEntry x entry) 


Retrieves the maximum allowed length of the text in entry. 


See gtk_entry_set_max_length(). 


Parameters: 


entry [in] a GtkEntry. 
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Returns: 


the maximum allowed number of characters in GtkEntry, or O 1f there is no maximum. 


6.36.3.10 GtkEntryNavigationMode gtk_entry_get_navigation_mode (GtkEntry x entry) 


Returns the current navigation Mode. 


Parameters: 


entry [in] a GtkEntry 


Returns: 


GtkEntryNavigationMode 


Since 


LIMO R1 


6.36.3.11 G_CONST_RETURN gchar» gtk_entry_get_prompt_string (GtkEntry * entry) 


Returns the string displayed during the unfocused state and entry is empty. 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


Prompt string 


Since 


LIMO RI 


6.36.3.12 guint gtk_entry_get_remaining_input_byte_count (GtkEntry x entry) 


Returns the count of remaining more number of bytes are allowed to add. 


Parameters: 


entry [in] a GtkEntry 


Returns: 


remaining number of bytes allowed to input. 


Since 


LIMO R1 
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6.36.3.13 guint gtk_entry_get_remaining_input_char_count (GtkEntry * entry) 


Returns the count of remaining more number of chars can be entered/added based on UTF-8 encoding. 
Parameters: 

entry [in] a GtkEntry 
Returns: 


remaining number of characters can be entered. 


Since 


LIMO R1 


6.36.3.14 G_CONST_RETURN gchar» gtk_entry_get_text (GtkEntry x entry) 


Retrieves the contents of the entry widget. 
See also gtk_editable_get_chars(). 
Parameters: 


entry [in] a GtkEntry. 


Returns: 


a pointer to the contents of the widget as a string. This string points to internally allocated storage in 
the widget and must not be freed, modified or stored. 


6.36.3.15 gboolean gtk_entry_get_visibility (GtkEntry x entry) 
Retrieves whether the text in entry is visible. 
See gtk_entry_set_visibility(). 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


TRUE if the text is currently visible 


6.36.3.16 gint gtk_entry_get_width_chars (GtkEntry « entry) 


Gets the characters size, .i.e. 


value set by gtk_entry_set_width_chars(). 


Parameters: 


entry [in] a GtkEntry. 


Returns: 


number of chars to request space for, or negative if unset 
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6.36.3.17 gint gtk_entry_layout_index_to_text_index (GtkEntry x entry, gint layout_index) 


Converts from a position in the entry contents (returned by gtk_entry_get_text()) to a position in the entry’s 
PangoLayout (returned by gtk_entry_get_layout(), with text retrieved via pango_layout_get_text()). 
Parameters: 


entry [in] a GtkEntry. 


layout_index [in] byte index into the entry layout text 


Returns: 


byte index into the entry contents 


6.36.3.18 GtkWidget« gtk_entry_new (void) 
Creates a new entry. 


Returns: 


anew GtkEntry. 


6.36.3.19 void gtk_entry_set_activates_default (GtkEntry x entry, gboolean setting) 
If setting is TRUE, pressing Enter in the entry will activate the default widget for the window containing 
the entry. 


This usually means that the dialog box containing the entry will be closed, since the default widget is 
usually one of the dialog buttons. 


(For experts: if setting is TRUE, the entry calls gtk_window_activate_default() on the window containing 
the entry, in the default handler for the "activate" signal.) 


Parameters: 


entry [in] a GtkEntry. 
setting [in] TRUE to activate window’s default widget on Enter keypress 


Returns: 


void 


6.36.3.20 void gtk_entry_set_alignment (GtkEntry x entry, gfloat xalign) 


Sets the alignment for the contents of the entry. 

This controls the horizontal positioning of the contents when the displayed text is shorter than the width of 
the entry. 

Parameters: 


entry [in] a GtkEntry. 
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xalign [in] The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts 


Returns: 


void 


6.36.3.21 void gtk_entry_set_completion (GtkEntry x entry, GtkEntryCompletion * completion) 


Sets completion to be the auxiliary completion object to use with entry. 


This can be used for Entry Completion and Specll check. 


Parameters: 
entry [in] a GtkEntry. 
completion [in] The GtkEntryCompletion or NULL.. 


Returns: 


void 


6.36.3.22 void gtk_entry_set_has_frame (GtkEntry x entry, gboolean setting) 
Sets whether the entry has a beveled frame around it. 


Parameters: 


entry [in] a GtkEntry. 


setting [in] new value 


Returns: 


void 


6.36.3.23 void gtk_entry_set_inner_border (GtkEntry * entry, const GtkBorder « border) 


Sets entry’s inner-border property to border, or clears it if NULL is passed. 
The inner-border is the area around the entry’s text, but inside its frame. 


Tf set, this property overrides the inner-border style property. Overriding the style-provided border is useful 
when you want to do in-place editing of some text in a canvas or list widget, where pixel-exact positioning 
of the entry is important. 


Parameters: 


entry [in] a GtkEntry. 
border [in] a GtkBorder, or NULL 


Returns: 


void 
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6.36.3.24 void gtk_entry_set_invisible_char (GtkEntry x entry, gunichar ch) 
Sets the character to use in place of the actual text when gtk_entry_set_visibility() has been called to set 
text visibility to FALSE. 


1.e. this is the character used in "password mode" to show the user how many characters have been typed. 
The default invisible char is an asterisk (’*’). If you set the invisible char to 0, then the user will get no 
feedback at all; there will be no text on the screen as they type 


Parameters: 


entry [in] a GtkEntry. 
ch [in] a Unicode character 


Returns: 


void 


6.36.3.25 void gtk_entry_set_max_length (GtkEntry + entry, gint max) 


Sets the maximum allowed length of the contents of the widget. 


Tf the current contents are longer than the given length, then they will be truncated to fit. 


Parameters: 


entry [in] a GtkEntry. 


max [in] the maximum length of the entry, or 0 for no maximum.The value passed in will be clamped 
to the range 0-65536. 


Returns: 


void 


6.36.3.26 void gtk_entry_set_navigation_mode (GtkEntry « entry, GtkEntryNavigationMode 
mode) 


Sets the Cursor movement mode. 


In GTK_ENTRY_MODE_NORMAL mode, navigation key event moves the cursor normally. In Mode 
GTK_ENTRY_MODE_SELECTION, navigation key events does Text Selection from the current posi- 
tion. If it is already in text selection mode, then selection will be extended based on the Navigation 
key untill mode is reset to GTK_ENTRY_MODE_NORMAL. Default mode is GTK_ENTRY_MODE - 
NORMAL. 


Parameters: 

entry [in] a GtkEntry 

mode [in] GtkEntryNavigationMode 
Returns: 

void 
Since 


LIMO RI 
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6.36.3.27 void gtk_entry_set_prompt_string (GtkEntry x entry, const gchar x text) 


Sets String displayed during the unfocused state and entry is empty. 


Parameters: 


entry [in] a GtkEntry. 


text [in] Prompt text 


Since 


LIMO RI 


6.36.3.28 void gtk_entry_set_text (GtkEntry x entry, const gchar + text) 
Sets the text in the widget to the given value, replacing the current contents. 


Parameters: 


entry [in] a GtkEntry. 


text [in] the new text. 


Returns: 


void 


6.36.3.29 void gtk_entry_set_visibility (GtkEntry « entry, gboolean visible) 


Sets whether the contents of the entry are visible or not. 


When visibility is set to FALSE, characters are displayed as the invisible char, and will also appear that 
way when the text in the entry widget is copied elsewhere. 


The default invisible char is the asterisk ’*’, but it can be changed with gtk_entry_set_invisible_char(). 


Parameters: 


entry [in] a GtkEntry. 
visible [in] TRUE if the contents of the entry are displayed as plaintext. 


Returns: 


1 when SUCCESSFUL, or 0 


6.36.3.30 void gtk_entry_set_width_chars (GtkEntry * entry, gint n_chars) 


Changes the size request of the entry to be about the right size for n_chars characters. 

Note that it changes the size request, the size can still be affected by how you pack the widget into contain- 
ers. If n_chars is -1, the size reverts to the default entry size. 

Parameters: 


entry [in] a GtkEntry. 
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n_charsa width in chars 


Returns: 


void 


6.36.3.31 gint gtk_entry_text_index_to_layout_index (GtkEntry x entry, gint text_index) 


Converts from a position in the entry’s PangoLayout (returned by gtk_entry_get_layout()) to a position in 
the entry contents (returned by gtk_entry_get_text()). 


Parameters: 


entry [in] a GtkEntry. 


text_index [in] byte index into the entry contents 


Returns: 


byte index into the entry layout text 
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6.37 GtkEntryCompletion 


6.37.1 Detailed Description 


GtkEntryCompletion is an auxiliary object to be used in conjunction with GtkEntry to provide the comple- 
tion functionality. 


It implements the GtkCellLayout interface, to allow the user to add extra cells to the GtkTree View with 
completion matches. 


"Completion functionality" means that when the user modifies the text in the entry, GtkEntryCompletion 
checks which rows in the model match the current content of the entry, and displays a list of matches. 
By default, the matching is done by comparing the entry text case-insensitively against the text column of 
the model (see gtk_entry_completion_set_text_column()), but this can be overridden with a custom match 
function (see gtk_entry_completion_set_match_func(). 


When the user selects a completion, the content of the entry is updated. By default, the content of the entry 
1s replaced by the text column of the model, but this can be overridden by connecting to the match-selected 
signal and updating the entry in the signal handler. Note that you should return TRUE from the signal 
handler to suppress the default behaviour. 


To add completion functionality to an entry, use gtk_entry_set_completion(). 


In addition to regular completion matches, which will be inserted into the entry when they are selected, 
GtkEntryCompletion also allows to display "actions" in the popup window. Their appearance is similar to 
menuitems, to differentiate them clearly from completion strings. When an action is selected, the action- 
activated signal is emitted. 


Entry Completion Infrastructure can be used for man purposes like Auto Completion, Spell check etc... 


Data Structures 


e struct _GtkEntryCompletion 


GtkEntryCompletion instance structure. 


e struct _GtkEntryCompletionClass 


GtkEntryCompletion instance class structure. 


Typedefs 


e typedef gboolean(* GtkEntryCompletionMatchFunc )(GtkEntryCompletion *completion, const 
gchar «key, GtkTreelter «iter, gpointer user_data) 


A function which decides whether the row indicated by iter matches a given key, and should be displayed as 
a possible completion for key. 


Functions 


e GtkEntryCompletion x gtk_entry_completion_new (void) 


Creates a new GtkEntryCompletion object. 


e GtkWidget x gtk_entry_completion_get_entry (GtkEntryCompletion *completion) 
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Gets the entry completion has been attached to. 


void gtk_entry_completion_set_model (GtkEntryCompletion completion,  GtkTreeModel 
model) 


Sets the model for a GtkEntryCompletion. 


GtkTreeModel x gtk_entry_completion_get_model (GtkEntryCompletion *completion) 


Returns the model the GtkEntryCompletion is using as data source. 


void gtk_entry_completion_set_match_func (GtkEntryCompletion *completion, GtkEntryComple- 
tionMatchFunc func, gpointer func_data, GDestroyNotify func_notify) 


Sets the match function for completion to be func. 


void gtk_entry_completion_set_minimum_key_length (GtkEntryCompletion *completion, gint 
length) 


Requires the length of the search key for completion to be at least length. 


gint gtk_entry_completion_get_minimum_key_length (GtkEntryCompletion *completion) 


Returns the minimum key length as set for completion. 


void gtk_entry_completion_complete (GtkEntryCompletion *completion) 


Requests a completion operation, or in other words a refiltering of the current list with completions, using 
the current key. 


void gtk_entry_completion_insert_prefix (GtkEntryCompletion *completion) 


Requests a prefix insertion. 


void gtk_entry_completion_insert_action_text (GtkEntryCompletion completion, gint index_- 
, const gchar xtext) 


Inserts an action in completion’s action item list at position index_ with text text. 


void gtk_entry_completion_insert_action_markup (GtkEntryCompletion *completion, gint index_, 
const gchar «*markup) 


Inserts an action in completion’s action item list at position index_ with markup markup. 


void gtk_entry_completion_delete_action (GtkEntryCompletion *completion, gint index_) 


Deletes the action at index_ from completion’s action list. 


void gtk entry_completion_set_inline_completion (GtkEntryCompletion *completion, gboolean 
inline_completion) 


Sets whether the common prefix of the possible completions should be automatically inserted in the entry. 


gboolean gtk_entry_completion_get_inline_completion (GtkEntryCompletion *completion) 


Returns whether the common prefix of the possible completions should be automatically inserted in the 
entry. 


void gtk_entry_completion_set_popup_completion (GtkEntryCompletion *completion, gboolean 
popup_completion) 


Sets whether the completions should be presented in a popup window. 


gboolean gtk_entry_completion_get_popup_completion (GtkEntryCompletion «completion) 
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Returns whether the completions should be presented in a popup window. 


e void gtk_entry_completion_set_popup_set_width (GtkEntryCompletion *completion, gboolean 
popup_set_width) 


Sets whether the completion popup window will be resized to be the same width as the entry. 


e gboolean gtk_entry_completion_get_popup_set_width (GtkEntryCompletion *completion) 


Returns whether the completion popup window will be resized to the width of the entry. 


e void gtk_entry_completion_set_popup_single_match (GtkEntryCompletion «completion, gboolean 
popup_single_match) 


Sets whether the completion popup window will appear even if there is only a single match. 


e gboolean gtk_entry_completion_get_popup_single_match (GtkEntryCompletion «completion) 


Returns whether the completion popup window will appear even if there is only a single match. 


e void gtk_entry_completion_set_text_column (GtkEntryCompletion «completion, gint column) 


Convenience function for setting up the most used case of this code: a completion list with just strings. 


e gint gtk_entry_completion_get_text_column (GtkEntryCompletion *completion) 


Returns the column in the model of completion to get strings from. 


6.37.2 Typedef Documentation 


6.37.2.1 typedef gboolean(« GtkEntryCompletionMatchFunc)(GtkEntryCompletion «completion, 
const gchar «key, GtkTreelter xiter, gpointer user_data) 


A function which decides whether the row indicated by iter matches a given key, and should be displayed 
as a possible completion for key. 


Note that key is normalized and case-folded (see g_utf8_normalize() and g_utf8_casefold()). If this is 
not appropriate, match functions have access to the unmodified key via gtk_entry_get_text (GTK_ENTRY 
(gtk_entry_completion_get_entry ())). 


Parameters: 


completion [in] A GtkEntryCompletion. 
key [in] the string to match, normalized and case-folded 
iter [in] a GtkTreelter indicating the row to match 


user_data [in] user data given to gtk_entry_completion_set_match_func() 


Returns: 


TRUE if iter should be displayed as a possible completion for key 


6.37.3 Function Documentation 
6.37.3.1 void gtk_entry_completion_complete (GtkEntryCompletion x completion) 


Requests a completion operation, or in other words a refiltering of the current list with completions, using 
the current key. 
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The completion list view will be updated accordingly. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


void 


6.37.3.2 void gtk_entry_completion_delete_action (GtkEntryCompletion x completion, gint 
index_) 


Deletes the action at index_ from completion’s action list. 


Parameters: 
completion [in] A GtkEntryCompletion. 


index_ [in] The index of the item to Delete. 


Returns: 


void 


6.37.3.3 GtkWidget» gtk_entry_completion_get_entry (GtkEntryCompletion x completion) 


Gets the entry completion has been attached to. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


The entry completion has been attached to. 


6.37.3.4 gboolean gtk_entry_completion_get_inline_completion (GtkEntryCompletion « 
completion) 


Returns whether the common prefix of the possible completions should be automatically inserted in the 
entry. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


TRUE if inline completion is turned on 
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6.37.3.5 gint gtk_entry_completion_get_minimum_key_length (GtkEntryCompletion x 
completion) 


Returns the minimum key length as set for completion. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


The currently used minimum key length. 


6.37.3.6 GtkTreeModelx gtk_entry_completion_get_model (GtkEntryCompletion x completion) 


Returns the model the GtkEntryCompletion is using as data source. 


Returns NULL if the model is unset. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


A GtkTreeModel, or NULL if none is currently being used. 


6.37.3.7 gboolean gtk_entry_completion_get_popup_completion (GtkEntryCompletion x 
completion) 


Returns whether the completions should be presented in a popup window. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


TRUE if popup completion is turned on 


6.37.3.8 gboolean gtk_entry_completion_get_popup_set_width (GtkEntryCompletion x 
completion) 


Returns whether the completion popup window will be resized to the width of the entry. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


TRUE if the popup window will be resized to the width of the entry 
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6.37.3.9 gboolean gtk_entry_completion_get_popup_single_match (GtkEntryCompletion « 
completion) 


Returns whether the completion popup window will appear even if there is only a single match. 


Parameters: 
completion [in] A GtkEntryCompletion. 


Returns: 


TRUE if the popup window will appear regardless of the number of matches. 


6.37.3.10 gint gtk_entry_completion get_text_column (GtkEntryCompletion x completion) 


Returns the column in the model of completion to get strings from. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


the column containing the strings 


6.37.3.11 void gtk_entry_completion_insert_action_markup (GtkEntryCompletion « completion, 
gint index_, const gchar x markup) 


Inserts an action in completion’s action item list at position index_ with markup markup. 


Parameters: 
completion [in] A GtkEntryCompletion. 
index_ [in] The index of the item to insert. 
markup [in] Markup of the item to insert. 
Returns: 


void 


6.37.3.12 void gtk_entry_completion_insert_action_text (GtkEntryCompletion * completion, gint 
index_, const gchar = text) 
Inserts an action in completion’s action item list at position index_ with text text. 


If you want the action item to have markup, use gtk_entry_completion_insert_action_markup(). 


Parameters: 
completion [in] A GtkEntryCompletion. 
index_ [in] The index of the item to insert.s 
markup [in] Text of the item to insert. 
Returns: 


void 
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6.37.3.13 void gtk_entry_completion_insert_prefix (GtkEntryCompletion * completion) 
Requests a prefix insertion. 


Parameters: 


completion [in] A GtkEntryCompletion. 


Returns: 


void 


6.37.3.14 GtkEntryCompletion« gtk_entry_completion_new (void) 
Creates a new GtkEntryCompletion object. 


Returns: 


A newly created GtkEntryCompletion object. 


6.37.3.15 void gtk_entry_completion_set_inline_completion (GtkEntryCompletion + completion, 
gboolean inline_completion) 


Sets whether the common prefix of the possible completions should be automatically inserted in the entry. 


Parameters: 


completion [in] A GtkEntryCompletion. 


inline_completion [in] TRUE to do inline completion 


Returns: 


void 


6.37.3.16 void gtk_entry_completion_set_match_func (GtkEntryCompletion * completion, 
GtkEntryCompletionMatchFunc func, gpointer func_data, GDestroyNotify func_notify) 
Sets the match function for completion to be func. 


The match function is used to determine if a row should or should not be in the completion list. 


Parameters: 


completion [in] A GtkEntryCompletion. 
func [in] The GtkEntryCompletionMatchFunc to use. 
func_data [in] The user data for func. 


func_notify [in] Destroy notifier for func_data. 


Returns: 


void 
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6.37.3.17 void gtk_entry_completion_set_minimum_key_length (GtkEntryCompletion * 
completion, gint length) 

Requires the length of the search key for completion to be at least length. 

This is useful for long lists, where completing using a small key takes a lot of time and will come up with 

meaningless results anyway (ie, a too large dataset). 

Parameters: 


completion [in] A GtkEntryCompletion. 


length [in] The minimum length of the key in order to start completing. 


Returns: 


void 


6.37.3.18 void gtk_entry_completion_set_model (GtkEntryCompletion x completion, 
GtkTreeModel x model) 
Sets the model for a GtkEntryCompletion. 


If completion already has a model set, it will remove it before setting the new model. If model is NULL, 
then it will unset the model. 


Parameters: 


completion [in] A GtkEntryCompletion. 
model [in] The GtkTreeModel. 


Returns: 


void 


6.37.3.19 void gtk_entry_completion_set_popup_completion (GtkEntryCompletion * completion, 
gboolean popup_completion) 


Sets whether the completions should be presented in a popup window. 


Parameters: 


completion [in] A GtkEntryCompletion. 
popup_completion [in] TRUE to do popup completion 


Returns: 


void 


6.37.3.20 void gtk_entry_completion_set_popup_set_width (GtkEntryCompletion x completion, 
gboolean popup_set_width) 


Sets whether the completion popup window will be resized to be the same width as the entry. 
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Parameters: 
completion [in] A GtkEntryCompletion. 
popup_set_width [in] TRUE to make the width of the popup the same as the entry 


Returns: 


void 


6.37.3.21 void gtk_entry_completion_set_popup_single_match (GtkEntryCompletion « 
completion, gboolean popup_single_match) 


Sets whether the completion popup window will appear even if there is only a single match. 


You may want to set this to FALSE if you are using inline completion. 


Parameters: 


completion [in] A GtkEntryCompletion. 
popup_single_match [in] TRUE if the popup should appear even for a single match 


Returns: 


void 


6.37.3.22 void gtk_entry_completion_set_text_column (GtkEntryCompletion « completion, gint 
column) 
Convenience function for setting up the most used case of this code: a completion list with just strings. 


This function will set up completion to have a list displaying all (and just) strings in the completion list, 
and to get those strings from column in the model of completion. 


This functions creates and adds a GtkCellRendererText for the selected column. If you need to set the text 
column, but don’t want the cell renderer, use g_object_set() to set the text_column property directly. 
Parameters: 

completion [in] A GtkEntryCompletion. 


column [in] The column in the model of completion to get strings from. 


Returns: 


void 
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6.38 GtkHScale 


6.38.1 Detailed Description 


This file defines the functions of GtkHScale. 


GtkWidget *hscale; 

GtkObject *adjl; 

GtkWidget xbox; 

box = gtk_vbox_new (FALSE, 10); 
gtk_container_add (GTK_CONTAINER (window), box); 
gtk_widget_show (box); 


adj1 = gtk_adjustment_new (0.0, 0.0, 101.0, 0.1, 1.0, 1.0); 


hscale = gtk_hscale_new (GTK_ADJUSTMENT (adjl)); 
gtk_widget_set_size_request (GTK_WIDGET (hscale), 200, 
scale_set_default_values (GTK_SCALE (hscale)); 
gtk_box_pack_start (GTK_BOX (box), hscale, TRUE, TRUE, 
gtk_widget_show (hscale); 


Data Structures 


e struct _GtkHScale 


GtkHScale instance structure. 


e struct _GtkHScaleClass 


GtkHScale instance class structure. 


Functions 


e GtkWidget * gtk_hscale_new (GtkAdjustment *adjustment) 


Creates a new GtkHScale. 


1); 


0; 


e GtkWidget * gtk_hscale_new_with_range (gdouble min, gdouble max, gdouble step) 


Creates a new horizontal scale widget that lets the user input a number between min and max (including 


min and max) with the increment step. 


6.38.2 Function Documentation 


6.38.2.1 GtkWidget» gtk_hscale_new (GtkAdjustment x adjustment) 


Creates a new GtkHScale. 


Parameters: 


adjustment [in] the GtkAdjustment which sets the range of the scale. 


Returns: 


a new GtkHScale 
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6.38.2.2 GtkWidget* gtk_hscale_new_with_range (gdouble min, gdouble max, gdouble step) 


Creates a new horizontal scale widget that lets the user input a number between min and max (including 
min and max) with the increment step. 


step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value. 
Note that the way in which the precision is derived works best if step is a power of ten. If the resulting 
precision is not suitable for your needs, use gtk_scale_set_digits() to correct it. 
Parameters: 

min [in] minimum value 

max [in] maximum value 


step [in] step increment (tick size) used with keyboard shortcuts. step must be nonzero; 


Returns: 


anew GtkHScale 
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6.39 GtkVScale 


6.39.1 Detailed Description 


The GtkVScale widget is used to allow the user to select a value using a vertical slider. 


To create one, use gtk_hscale_new_with_range(). 


The position to show the current value, and the number of decimal places shown can be set using the parent 
GtkScale class’s functions. 


Code Example 


GtkWidget *vscale; 
GtkObject *adj31l; 
GtkWidget xbox; 


box = gtk_vbox_new (FALSE, 10); 

gtk_container_add (GTK_CONTAINER (window), box); 
gtk_widget_show (box); 

adj1 = gtk_adjustment_new (0.0, 0.0, 101.0, 0.1, 1.0, 1.0); 
vscale = gtk_vscale_new (GTK_ADJUSTMENT (adjl)); 
scale_set_default_values (GTK_SCALE (vscale)); 
gtk_box_pack_start (GTK_BOX (box), vscale, TRUE, TRUE, 0); 
gtk_widget_show (vscale); 


Data Structures 


e struct _GtkV Scale 


GtkVScale instance structure. 


e struct _GtkVScaleClass 


GtkVScale instance class structure. 


Functions 


e GtkWidget * gtk_vscale_new (GtkAdjustment *adjustment) 


Creates a new GtkVScale. 


e GtkWidget * gtk_vscale_new_with_range (gdouble min, gdouble max, gdouble step) 


Creates a new vertical scale widget that lets the user input a number between min and max (including min 
and max) with the increment step. 


6.39.2 Function Documentation 
6.39.2.1 GtkWidget* gtk_vscale_new (GtkAdjustment * adjustment) 
Creates a new GtkVScale. 


Parameters: 


adjustment [in] the GtkAdjustment which sets the range of the scale. 
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Returns: 


a new GtkVScale. 


6.39.2.2 GtkWidget* gtk_vscale_new_with_range (gdouble min, gdouble max, gdouble step) 


Creates a new vertical scale widget that lets the user input a number between min and max (including min 
and max) with the increment step. 


step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value. 
Note that the way in which the precision is derived works best if step is a power of ten. If the resulting 
precision is not suitable for your needs, use gtk_scale_set_digits() to correct it. 

Parameters: 


min [in] vertical scale minimum value 
max [in] vertical scale maximum value 


step [in] step increment (tick size) used with keyboard shortcuts. 


Note: 


step must be nonzero; 


Returns: 


anew GtkVScale 
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6.40 GtkEditable 


6.40.1 Detailed Description 
The GtkEditable interface is an interface which should be implemented by text editing widgets, such as 
GtkEntry and GtkText. 


It contains functions for generically manipulating an editable widget, a large number of action signals used 
for key bindings, and several signals that an application can connect to to modify the behavior of a widget. 


As an example of the latter usage, by connecting the following handler to "insert_text", an application can 
convert all entry into a widget into uppercase. 


Code Example 


#include <ctype.h> 


void insert_text_handler ( GtkEditable x*editable, 
const gchar «text, 


gint length, 
gint *position, 
gpointer data) 


int i; 
gchar *result = g_utf8_strup (text, length); 
g_signal_handlers_block_by_func (editable, 

(gpointer) insert_text_handler, data); 
gtk_editable_insert_text (editable, result, length, position); 
g_signal_handlers_unblock_by_func (editable, 

(gpointer) insert_text_handler, data); 


g_signal_stop_emission_by_name (editable, "insert_text"); 


g_free (result); 


Data Structures 


e struct _GtkEditableClass 


GtkEditable instance class structure. 


Functions 


e void gtk_editable_select_region (GtkEditable «editable, gint start, gint end) 


Selects a region of text. 


e gboolean gtk_editable_get_selection_bounds (GtkEditable «editable, gint «start, gint *end) 


Gets the current selection bounds, if there is a selection. 


e void gtk_editable_insert_text (GtkEditable x*editable, const gchar *new_text, gint new_text_length, 
gint *position) 


Inserts text at a given position. 


e void gtk_editable_delete_text (GtkEditable «editable, gint start_pos, gint end_pos) 
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Deletes a sequence of characters. 


e gchar * gtk_editable_get_chars (GtkEditable *editable, gint start_pos, gint end_pos) 


Retrieves a sequence of characters. 


e void gtk_editable_cut_clipboard (GtkEditable x*editable) 


Causes the characters in the current selection to be copied to the clipboard and then deleted from the widget. 


e void gtk_editable_copy_clipboard (GtkEditable *editable) 


Causes the characters in the current selection to be copied to the clipboard. 


e void gtk_editable_paste_clipboard (GtkEditable *editable) 


Causes the contents of the clipboard to be pasted into the given widget at the current cursor position. 


e void gtk_editable_delete_selection (GtkEditable «editable) 


Deletes the current contents of the widgets selection and disclaims the selection. 


e void gtk_editable_set_position (GtkEditable editable, gint position) 


Sets the cursor position. 


e gint gtk_editable_get_position (GtkEditable *editable) 


Retrieves the current cursor position. 


e void gtk_editable_set_editable (GtkEditable «editable, gboolean is_editable) 


Determines if the user can edit the text in the editable widget or not. 


e gboolean gtk_editable_get_editable (GtkEditable «editable) 


Retrieves whether editable is editable. 


6.40.2 Function Documentation 
6.40.2.1 void gtk_editable_copy_clipboard (GtkEditable x editable) 
Causes the characters in the current selection to be copied to the clipboard. 


Parameters: 


editable [in] A GtkEditable. 


Returns: 


void 


6.40.2.2 void gtk_editable_cut_clipboard (GtkEditable « editable) 
Causes the characters in the current selection to be copied to the clipboard and then deleted from the widget. 


Parameters: 


editable [in] a GtkEditable widget. 
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Returns: 


void 


6.40.2.3 void gtk_editable_delete_selection (GtkEditable « editable) 
Deletes the current contents of the widgets selection and disclaims the selection. 


Parameters: 


editable [in] A GtkEditable. 


Returns: 


void 


6.40.2.4 void gtk_editable_delete_text (GtkEditable x editable, gint start_pos, gint end_pos) 


Deletes a sequence of characters. 


The characters that are deleted are those characters at positions from start_pos up to, but not including 
end_pos. If end_pos is negative, then the the characters deleted will be those characters from start_pos to 
the end of the text. 


Parameters: 


editable [in] a GtkEditable widget. 
start_pos [in] the starting position. 


end_pos [in] the end position. 


Returns: 


void 


6.40.2.5 gchar» gtk_editable_get_chars (GtkEditable x editable, gint start_pos, gint end_pos) 


Retrieves a sequence of characters. 


The characters that are retrieved are those characters at positions from start_pos up to, but not including 
end_pos. If end_pos is negative, then the the characters retrieved will be those characters from start_pos to 
the end of the text. 
Parameters: 

editable [in] a GtkEditable widget. 

start_pos [in] the starting position. 


end_pos [in] the end position. 


Returns: 


the characters in the indicated region. The result must be freed with g_free() when the application is 
finished with it. 
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6.40.2.6 gboolean gtk_editable_get_editable (GtkEditable « editable) 


Retrieves whether editable is editable. 


See gtk_editable_set_editable(). 


Parameters: 


editable [in] A GtkEditable. 


Returns: 


TRUE if editable is editable. 


6.40.2.7 gint gtk_editable_get_position (GtkEditable * editable) 
Retrieves the current cursor position. 


Parameters: 


editable [in] a GtkEditable widget. 


Returns: 


the position of the cursor. The cursor is displayed before the character with the given (base 0) index in 
the widget. The value will be less than or equal to the number of characters in the widget. Note that 
this position is in characters, not in bytes. 


6.40.2.8 gboolean gtk_editable_get_selection_bounds (GtkEditable « editable, gint x start, gint « 
end) 


Gets the current selection bounds, if there is a selection. 


Parameters: 


editable [in] a GtkEditable widget. 
— start [in] location to store the starting position, or NULL. 


— end [in] location to store the end position, or NULL. 


Returns: 


TRUE if there is a selection. 


6.40.2.9 void gtk_editable_insert_text (GtkEditable x editable, const gchar x new_text, gint 
new_text_length, gint x position) 


Inserts text at a given position. 


Parameters: 


editable [in] a GtkEditable widget. 


new_text [in] the text to insert. 
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new_text_length [in] the length of the text to insert, in bytes 


position [in] an inout parameter. The caller initializes it to the position at which to insert the text. 
After the call it points at the position after the newly inserted text. 


Returns: 


void 


6.40.2.10 void gtk_editable_paste_clipboard (GtkEditable « editable) 
Causes the contents of the clipboard to be pasted into the given widget at the current cursor position. 


Parameters: 


editable [in] A GtkEditable. 


Returns: 


void 


6.40.2.11 void gtk_editable_select_region (GtkEditable x editable, gint start, gint end) 


Selects a region of text. 


The characters that are selected are those characters at positions from start_pos up to, but not including 
end_pos. If end_pos is negative, then the the characters selected will be those characters from start_pos to 
the end of the text. 


Parameters: 


editable [in] a GtkEditable widget. 
start [in] the starting position. 


end [in] the end position. 


Returns: 


void 


6.40.2.12 void gtk_editable_set_editable (GtkEditable « editable, gboolean is_editable) 
Determines if the user can edit the text in the editable widget or not. 


Parameters: 


editable [in] a GtkEditable widget. 
is_editable [in] TRUE if the user is allowed to edit the text in the widget. 


Returns: 


void 
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6.40.2.13 void gtk_editable_set_position (GtkEditable x editable, gint position) 
Sets the cursor position. 


Parameters: 


editable [in] a GtkEditable widget. 


position [in] the position of the cursor. The cursor is displayed before the character with the given 
(base 0) index in the widget. The value must be less than or equal to the number of characters in 
the widget. A value of -1 indicates that the position should be set after the last character in the 
entry. Note that this position is in characters, not in bytes. 


Returns: 


void 
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6.41 Multiline Text Editor 


Modules 


GtkTextlter 


Text buffer iterator. 


GtkTextMark 


A position in the buffer preserved across buffer modifications. 


GtkTextBuffer 
This file defines the functions of GtkTextBuffer. 


GtkTextTag 
A tag that can be applied to text in a GtkTextBuffer. 


GtkTextTagTable 


Collection of tags that can be used together. 


GtkTextView 
Widget that displays a GtkTextBuffer, in Multiline. 
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6.42 GtkTextIter 


6.42.1 Detailed Description 


Text buffer iterator. 


You may wish to begin by reading the text widget conceptual overview which gives an overview of all the 
objects and data types related to the text widget and how they work together. 


Data Structures 


e struct _GtkTextlter 


GtkTextlter instance structure. 


Functions 


GtkTextBuffer x gtk_text_iter_get_buffer (const GtkTextlter xiter) 


Returns the GtkTextBuffer this iterator is associated with. 


e GtkTextlter x gtk_text_iter_copy (const GtkTextlter xiter) 


Creates a dynamically-allocated copy of an iterator. 


e void gtk_text_iter_free (GtkTextlter xiter) 


Free an iterator allocated on the heap. 


e gint gtk_text_iter_get_offset (const GtkTextlter xiter) 


Returns the character offset of an iterator. 


e gint gtk_text_iter_get_line (const GtkTextlter xiter) 


Returns the line number containing the iterator. 


e gint gtk_text_iter_get_line_offset (const GtkTextlter xiter) 


Returns the character offset of the iterator, counting from the start of a newline-terminated line. 


e gint gtk_text_iter_get_line_index (const GtkTextlter xiter) 


Returns the byte index of the iterator, counting from the start of a newline-terminated line. 


e gint gtk_text_iter_get_visible_line_offset (const GtkTextlter xiter) 


Returns the offset in characters from the start of the line to the given iter, not counting characters that are 
invisible due to tags with the "invisible" flag toggled on. 


e gint gtk_text_iter_get_visible_line_index (const GtkTextlter xiter) 


Returns the number of bytes from the start of the line to the given iter, not counting bytes that are invisible 
due to tags with the "invisible" flag toggled on. 


e gunichar gtk_text_iter_get_char (const GtkTextlter xiter) 


Returns the Unicode character at this iterator. 


e gchar x gtk_text_iter_get_slice (const GtkTextlIter «start, const GtkTextlter xend) 
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Returns the text in the given range. 


gchar * gtk_text_iter_get_text (const GtkTextlter «start, const GtkTextlter x*end) 


Returns text in the given range. 


gchar * gtk_text_iter_get_visible_slice (const GtkTextlter *start, const GtkTextlter *end) 


Like gtk_text_iter_get_slice(), but invisible text is not included. 


gchar * gtk_text_iter_get_visible_text (const GtkTextlter «start, const GtkTextlter *end) 


Returns the number of bytes from the start of the line to the given iter, not counting bytes that are invisible 
due to tags with the "invisible" flag toggled on. 


GdkPixbuf x gtk_text_iter_get_pixbuf (const GtkTextlter xiter) 


If the element at iter is a pixbuf, the pixbuf is returned (with no new reference count added). 


GSList * gtk_text_iter_get_marks (const GtkTextlter xiter) 


Returns a list of all GtkTextMark at this location. 


GtkTextChildAnchor x gtk_text_iter_get_child_anchor (const GtkTextlter xiter) 


If the location at iter contains a child anchor, the anchor is returned (with no new reference count added). 


GSList * gtk_text_iter_get_toggled_tags (const GtkTextlter xiter, gboolean toggled_on) 


Returns a list of GtkTextTag that are toggled on or off at this point. 


gboolean gtk_text_iter_begins_tag (const GtkTextlter xiter, GtkTextTag tag) 


Returns TRUE if tag is toggled on at exactly this point. 


gboolean gtk_text_iter_ends_tag (const GtkTextlter xiter, GtkTextTag *tag) 
Returns TRUE if tag is toggled off at exactly this point. 


gboolean gtk_text_iter_toggles_tag (const GtkTextlter xiter, GtkTextTag *tag) 


This is equivalent to (gtk_text_iter_begins_tag() || gtk_text_iter_ends_tag()), i.e. 


gboolean gtk_text_iter_has_tag (const GtkTextlter xiter, GtkTextTag *tag) 


Returns TRUE if iter is within a range tagged with tag. 


GSList x gtk_text_iter_get_tags (const GtkTextlter xiter) 


Returns a list of tags that apply to iter, in ascending order of priority (highest-priority tags are last). 


gboolean gtk_text_iter_editable (const GtkTextlter xiter, gboolean default_setting) 


Returns whether the character at iter is within an editable region of text. 


gboolean gtk_text_iter_can_insert (const GtkTextlter «iter, gboolean default_editability) 


Considering the default editability of the buffer, and tags that affect editability, determines whether text 
inserted at iter would be editable. 


gboolean gtk_text_iter_starts_word (const GtkTextlter *iter) 


Determines whether iter begins a natural-language word. 


gboolean gtk_text_iter_ends_word (const GtkTextlter iter) 
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Determines whether iter ends a natural-language word. 


e gboolean gtk_text_iter_inside_word (const GtkTextlter xiter) 


Determines whether iter is inside a natural-language word (as opposed to say inside some whitespace). 


e gboolean gtk_text_iter_starts_sentence (const GtkTextlter xiter) 


Determines whether iter begins a sentence. 


e gboolean gtk_text_iter_ends_sentence (const GtkTextlter xiter) 


Determines whether iter ends a sentence. 


e gboolean gtk_text_iter_inside_sentence (const GtkTextlter xiter) 


Determines whether iter is inside a sentence (as opposed to in between two sentences, e.g. 


e gboolean gtk_text_iter_starts_line (const GtkTextlter xiter) 


Returns TRUE if iter begins a paragraph, i.e. 


e gboolean gtk_text_iter_ends_line (const GtkTextlter xiter) 


Returns TRUE if iter points to the start of the paragraph delimiter characters for a line (delimiters will 
be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph 
separator character). 


e gboolean gtk_text_iter_is_cursor_position (const GtkTextlter xiter) 


See gtk_text_iter_forward_cursor_position() or PangoLogAttr or pango_break() for details on what a cur- 
sor position is. 


e gint gtk_text_iter_get_chars_in_line (const GtkTextlter xiter) 


Returns the number of characters in the line containing iter, including the paragraph delimiters. 


e gint gtk_text_iter_get_bytes_in_line (const GtkTextlter xiter) 


Returns the number of bytes in the line containing iter, including the paragraph delimiters. 


e gboolean gtk_text_iter_get_attributes (const GtkTextlter xiter, GtkTextAttributes *values) 


Computes the effect of any tags applied to this spot in the text. 


e PangoLanguage x gtk_text_iter_get_language (const GtkTextlter xiter) 


A convenience wrapper around gtk_text_iter_get_attributes(), which returns the language in effect at iter. 


e gboolean gtk_text_iter_is_end (const GtkTextlter xiter) 


Returns TRUE if iter is the end iterator, i.e. 


e gboolean gtk_text_iter_is_start (const GtkTextlter xiter) 


Returns TRUE if iter is the first iterator in the buffer, that is if iter has a character offset of 0. 


e gboolean gtk_text_iter_forward_char (GtkTextlter xiter) 


Moves iter forward by one character offset. 


e gboolean gtk_text_iter_backward_char (GtkTextlter xiter) 


Moves backward by one character offset. 
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gboolean gtk_text_iter_forward_chars (GtkTextlter xiter, gint count) 


Moves count characters if possible (if count would move past the start or end of the buffer, moves to the start 
or end of the buffer). 


gboolean gtk_text_iter_backward_chars (GtkTextlter *iter, gint count) 


Moves count characters backward, if possible (if count would move past the start or end of the buffer, moves 
to the start or end of the buffer). 


gboolean gtk_text_iter_forward_line (GtkTextlter xiter) 


Moves iter to the start of the next line. 


gboolean gtk_text_iter_backward_line (GtkTextlter xiter) 


Moves iter to the start of the previous line. 


gboolean gtk_text_iter_forward_lines (GtkTextlter xiter, gint count) 


Moves count lines forward, if possible (if count would move past the start or end of the buffer, moves to the 
start or end of the buffer). 


gboolean gtk_text_iter_backward_lines (GtkTextlter xiter, gint count) 


Moves count lines backward, if possible (if count would move past the start or end of the buffer, moves to 
the start or end of the buffer). 


gboolean gtk_text_iter_forward_word_end (GtkTextlter xiter) 


Moves forward to the next word end. 


gboolean gtk_text_iter_backward_word_start (GtkTextlter xiter) 


Moves backward to the previous word start. 


gboolean gtk_text_iter_forward_word_ends (GtkTextlter xiter, gint count) 


Calls gtk_text_iter_forward_word_end() up to count times. 


gboolean gtk_text_iter_backward_word_starts (GtkTextlter «iter, gint count) 


Calls gtk_text_iter_backward_word_start() up to count times. 


gboolean gtk_text_iter_forward_visible_line (GtkTextlter xiter) 


Moves iter to the start of the next visible line. 


gboolean gtk_text_iter_backward_visible_line (GtkTextlter xiter) 


Moves iter to the start of the previous visible line. 


gboolean gtk_text_iter_forward_visible_lines (GtkTextlter xiter, gint count) 


Moves count visible lines forward, if possible (if count would move past the start or end of the buffer, moves 
to the start or end of the buffer). 


gboolean gtk_text_iter_backward_visible_lines (GtkTextlter «iter, gint count) 


Moves count visible lines backward, if possible (if count would move past the start or end of the buffer, 
moves to the start or end of the buffer). 


gboolean gtk_text_iter_forward_visible_word_end (GtkTextlter xiter) 


Moves forward to the next visible word end. 
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e gboolean gtk_text_iter_backward_visible_word_start (GtkTextlter «iter) 


Moves backward to the previous visible word start. 


e gboolean gtk_text_iter_forward_visible_word_ends (GtkTextlter xiter, gint count) 


Calls gtk_text_iter_forward_visible_word_end() up to count times. 


e gboolean gtk_text_iter_backward_visible_word_starts (GtkTextlter xiter, gint count) 


Calls gtk_text_iter_backward_visible_word_start() up to count times. 


e gboolean gtk_text_iter_forward_sentence_end (GtkTextlter xiter) 


Moves forward to the next sentence end. 


e gboolean gtk_text_iter_backward_sentence_start (GtkTextlter xiter) 


Moves backward to the previous sentence start; if iter is already at the start of a sentence, moves backward 
to the next one. 


e gboolean gtk_text_iter_forward_sentence_ends (GtkTextlter xiter, gint count) 


Calls gtk_text_iter_forward_sentence_end() count times (or until gtk_text_iter_forward_sentence_end() re- 
turns FALSE). 


e gboolean gtk_text_iter_backward_sentence_starts (GtkTextlter xiter, gint count) 


Calls gtk_text_iter_backward_sentence_start() up to count times, or until it returns FALSE. 


e gboolean gtk_text_iter_forward_cursor_position (GtkTextlter xiter) 


cursor positions are almost equivalent to chars, but not quite; in some languages, you can't put the cursor 
between certain chars. 


e gboolean gtk_text_iter_backward_cursor_position (GtkTextlter xiter) 


Like gtk_text_iter_forward_cursor_position(), but moves backward. 


e gboolean gtk_text_iter_forward_cursor_positions (GtkTextlter xiter, gint count) 


Moves up to count cursor positions. 


e gboolean gtk_text_iter_backward_cursor_positions (GtkTextlter xiter, gint count) 


Moves up to count cursor positions. 


e gboolean gtk_text_iter_forward_visible_cursor_position (GtkTextlter xiter) 


Moves iter forward to the next visible cursor position. 


e gboolean gtk_text_iter_backward_visible_cursor_position (GtkTextlter xiter) 


Moves iter forward to the previous visible cursor position. 


e gboolean gtk_text_iter_forward_visible_cursor_positions (GtkTextlter xiter, gint count) 


Moves up to count visible cursor positions. 


e gboolean gtk_text_iter_backward_visible_cursor_positions (GtkTextlter «iter, gint count) 


Moves up to count visible cursor positions. 


e void gtk_text_iter_set_offset (GtkTextlter «iter, gint char_offset) 


Sets iter to point to char_offset. 
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void gtk_text_iter_set_line (GtkTextlter «iter, gint line_number) 


Moves iterator iter to the start of the line line_number. 


void gtk_text_iter_set_line_offset (GtkTextlter «iter, gint char_on_line) 


Moves iter within a line, to a new character (not byte) offset. 


void gtk_text_iter_set_line_index (GtkTextlter xiter, gint byte_on_line) 


Same as gtk_text_iter_set_line_offset(), but works with a byte index. 


void gtk_text_iter_forward_to_end (GtkTextlter xiter) 


Moves iter forward to the "end iterator," which points one past the last valid character in the buffer. 


gboolean gtk_text_iter_forward_to_line_end (GtkTextlter xiter) 


Moves the iterator to point to the paragraph delimiter characters, which will be either a newline, a carriage 
return, a carriage return/newline in sequence, or the Unicode paragraph separator character. 


void gtk_text_iter_set_visible_line_offset (GtkTextlter «iter, gint char_on_line) 


Like gtk_text_iter_set_line_offset(), but the offset is in visible characters, i.e. 


void gtk_text_iter_set_visible_line_index (GtkTextlter «iter, gint byte_on_line) 


Like gtk_text_iter_set_line_index(), but the index is in visible bytes, i.e. 


gboolean gtk_text_iter_forward_to_tag_ toggle (GtkTextlter xiter, GtkTextTag x*tag) 


Moves forward to the next toggle (on or off) of the GtkTextTag tag, or to the next toggle of any tag if tag is 
NULL. 


gboolean gtk_text_iter_backward_to_tag_toggle (GtkTextlter xiter, GtkTextTag *tag) 


Moves backward to the next toggle (on or off) of the GtkTextTag tag, or to the next toggle of any tag if tag is 
NULL. 


gboolean gtk_text_iter_forward_find_char (GtkTextlter «iter, GtkTextCharPredicate pred, gpointer 
user_data, const GtkTextlter «limit) 


Advances iter, calling pred on each character. 


gboolean gtk_text_iter_backward_find_char (GtkTextlter xiter, GtkTextCharPredicate pred, gpointer 
user_data, const GtkTextlter «limit) 


Same as gtk_text_iter_forward_find_char(), but goes backward from iter. 


gboolean gtk_text_iter_forward_search (const GtkTextlter xiter, const gchar «str, GtkTextSearch- 
Flags flags, GtkTextlter «*match_start, GtkTextlter *match_end, const GtkTextlter «limit) 


Searches forward for str. 


gboolean gtk_text_iter_backward_search (const GtkTextlter xiter, const gchar «str, GtkTextSearch- 
Flags flags, GtkTextlter «*match_start, GtkTextlter *match_end, const GtkTextlter «limit) 


Same as gtk_text_iter_forward_search(), but moves backward. 


gint gtk_text_iter_compare (const GtkTextlter «lhs, const GtkTextlter +rhs) 


A qsort()-style function that returns negative if lhs is less than rhs, positive if lhs is greater than rhs, and 0 
if they're equal. 
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e gboolean gtk_text_iter_in_range (const GtkTextlter xiter, const GtkTextlter «start, const GtkTextlter 
*end) 


Checks whether iter falls in the range [start, end). 


e void gtk_text_iter_order (GtkTextlter «first, GtkTextlter *second) 


Swaps the value of first and second if second comes before first in the buffer. 


6.42.2 Function Documentation 
6.42.2.1 gboolean gtk_text_iter_backward_char (GtkTextIter + iter) 


Moves backward by one character offset. 


Returns TRUE if movement was possible; if iter was the first in the buffer (character offset 0), gtk_text_- 
iter_backward_char() returns FALSE for convenience when writing loops. 


Parameters: 


iter [in] an iterator 


Returns: 


whether movement was possible 


6.42.2.2 gboolean gtk_text_iter_backward_chars (GtkTextlter x iter, gint count) 
Moves count characters backward, if possible (if count would move past the start or end of the buffer, 
moves to the start or end of the buffer). 


The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t 
move, or moved onto the end iterator, then FALSE is returned. If count is 0, the function does nothing and 
returns FALSE. 


Parameters: 


iter [in] an iterator 


count [in] number of characters to move, 


Returns: 


whether iter moved and is dereferenceable 


6.42.2.3 gboolean gtk_text_iter_backward_cursor_position (GtkTextlter + iter) 


Like gtk_text_iter_forward_cursor_position(), but moves backward. 


Parameters: 


iter [in] an iterator 


Returns: 


TRUE if we moved 
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6.42.2.4 gboolean gtk_text_iter_backward_cursor_positions (GtkTextlter « iter, gint count) 


Moves up to count cursor positions. 


See gtk_text_iter_forward_cursor_position() for details. 


Parameters: 
iter [in] an iterator 


iter [in] number of positions to move 


Returns: 


TRUE if we moved and the new position is dereferenceable 


6.42.2.5 gboolean gtk_text_iter_backward_find_char (GtkTextlter x iter, GtkTextCharPredicate 
pred, gpointer user_data, const GtkTextlter x limit) 


Same as gtk_text_iter_forward_find_char(), but goes backward from iter. 


Parameters: 
iter [in] a GtkTextlter 
pred [in] function to be called on each character 
user_data [in] user data for pred 


limit [in] search limit, or NULL for none 


Returns: 


whether a match was found 


6.42.2.6 gboolean gtk_text_iter_backward_line (GtkTextlter x iter) 


Moves iter to the start of the previous line. 


Returns TRUE if iter could be moved; i.e. if iter was at character offset 0, this function returns FALSE. 
Therefore if iter was already on line 0, but not at the start of the line, iter is snapped to the start of the line 
and the function returns TRUE. (Note that this implies that in a loop calling this function, the line number 
may not change on every iteration, if your first iteration is on line 0.) 


Parameters: 


iter [in] an iterator 


Returns: 


whether iter moved 
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6.42.2.7 gboolean gtk_text_iter_backward_lines (GtkTextlter x iter, gint count) 
Moves count lines backward, if possible (1f count would move past the start or end of the buffer, moves to 
the start or end of the buffer). 


The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t 
move, or moved onto the end iterator, then FALSE is returned. If count is 0, the function does nothing and 
returns FALSE. If count is negative, moves forward by 0 - count lines. 


Parameters: 
iter [in] an iterator 


count [in] number of lines to move backward 


Returns: 


whether iter moved and is dereferenceable 


6.42.2.8 gboolean gtk_text_iter_backward_search (const GtkTextlter x iter, const gchar + str, 
GtkTextSearchFlags flags, GtkTextlter x match_start, GtkTextIter x match_end, const 
GtkTextlIter x limit) 


Same as gtk_text_iter_forward_search(), but moves backward. 


Parameters: 


iter [in] a GtkTextlter where the search begins 

str [in] a search string 

flags [in] bitmask of flags affecting the search 

match_start [out] return location for start of match, or NULL 
match_end [out] return location for end of match, or NULL 


limit [out] location of last possible match_start, or NULL for start of buffer 


Returns: 


whether a match was found 


6.42.2.9 gboolean gtk_text_iter_backward_sentence_start (GtkTextIter + iter) 
Moves backward to the previous sentence start; if iter is already at the start of a sentence, moves backward 
to the next one. 


Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the 
correct fix would be to the Pango text boundary algorithms). 


Parameters: 


iter [in] an iterator 


Returns: 


TRUE if iter moved and is not the end iterator 
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6.42.2.10  gboolean gtk_text_iter_backward_sentence_starts (GtkTextlter x iter, gint count) 


Calls gtk_text_iter_backward_sentence_start() up to count times, or until it returns FALSE. 


If count is negative, moves forward instead of backward. 


Parameters: 
iter [in] an iterator 


count [in] number of sentences to move 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.11 gboolean gtk_text_iter_backward_to_tag_toggle (GtkTextlter « iter, GtkTextTag x tag) 
Moves backward to the next toggle (on or off) of the GtkTextTag tag, or to the next toggle of any tag if tag 
is NULL. 


If no matching tag toggles are found, returns FALSE, otherwise TRUE. Does not return toggles located at 
iter, only toggles before iter. Sets iter to the location of the toggle, or the start of the buffer if no toggle is 
found. 


Parameters: 
iter [in] an iterator 
tag [in] a GtkTextTag, or NULL 


Returns: 


whether we found a tag toggle before iter 


6.42.2.12 gboolean gtk_text_iter_backward_visible_cursor_position (GtkTextlter « iter) 


Moves iter forward to the previous visible cursor position. 


See gtk_text_iter_backward_cursor_position() for details 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if we moved and the new position is dereferenceable 


6.42.2.13 gboolean gtk_text_iter_backward_visible_cursor_positions (GtkTextlter x iter, gint 
count) 


Moves up to count visible cursor positions. 


See gtk_text_iter_backward_cursor_position() for details. 
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Parameters: 


iter [in] a GtkTextlter 


count [in] number of positions to move 


Returns: 


TRUE if we moved and the new position is dereferenceable 


6.42.2.14 gboolean gtk_text_iter_backward_visible_line (GtkTextIter + iter) 


Moves iter to the start of the previous visible line. 


Returns TRUE if iter could be moved; i.e. if iter was at character offset 0, this function returns FALSE. 
Therefore if iter was already on line 0, but not at the start of the line, iter is snapped to the start of the line 
and the function returns TRUE. (Note that this implies that in a loop calling this function, the line number 
may not change on every iteration, if your first iteration is on line 0.) 


Parameters: 


iter [in] an iterator 


Returns: 


whether iter moved 


6.42.2.15 gboolean gtk_text_iter_backward_visible_lines (GtkTextlIter x iter, gint count) 
Moves count visible lines backward, if possible Gf count would move past the start or end of the buffer, 
moves to the start or end of the buffer). 


The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t 
move, or moved onto the end iterator, then FALSE is returned. If count is 0, the function does nothing and 
returns FALSE. If count is negative, moves forward by 0 - count lines 


Parameters: 
iter [in] an iterator 
count [in] number of lines to move backward 


Returns: 


whether iter moved and is dereferenceable 


6.42.2.16 gboolean gtk_text_iter_backward_visible_word_start (GtkTextIter + iter) 


Moves backward to the previous visible word start. 


(If iter is currently on a word start, moves backward to the next one after that.) Word breaks are determined 
by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word 
break algorithms). 


Parameters: 


iter [in] an iterator 
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Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.17 gboolean gtk_text_iter_backward_visible_word_starts (GtkTextlter x iter, gint count) 
Calls gtk_text_iter_backward_visible_word_start() up to count times. 


Parameters: 


iter [in] an iterator 


count [in] number of times to move 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.18 gboolean gtk_text_iter_backward_word_start (GtkTextlter x iter) 


Moves backward to the previous word start. 


(If iter is currently on a word start, moves backward to the next one after that.) Word breaks are determined 
by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word 
break algorithms). 


Parameters: 


iter [in] an iterator 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.19 gboolean gtk_text_iter_backward_word_starts (GtkTextlter x iter, gint count) 
Calls gtk_text_iter_backward_word_start() up to count times. 


Parameters: 
iter [in] an iterator 


count [in] number of times to move 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.20 gboolean gtk_text_iter_begins_tag (const GtkTextlter x iter, GtkTextTag x tag) 


Returns TRUE if tag is toggled on at exactly this point. 


If tag is NULL, returns TRUE if any tag is toggled on at this point. Note that the gtk_text_iter_begins_tag() 
returns TRUE if iter is the start of the tagged range; gtk_text_iter_has_tag() tells you whether an iterator is 
within a tagged range. 
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Parameters: 

iter [in] an iterator 

tag [in] a GtkTextTag, or NULL 
Returns: 


whether iter is the start of a range tagged with tag 


6.42.2.21 gboolean gtk_text_iter_can_insert (const GtkTextlter + iter, gboolean default_editability) 
Considering the default editability of the buffer, and tags that affect editability, determines whether text 
inserted at iter would be editable. 


If text inserted at iter would be editable then the user should be allowed to insert text at iter. gtk_text_- 
buffer_insert_interactive() uses this function to decide whether insertions are allowed at a given posi- 
tion. 


Parameters: 

iter [in] an iterator 

default_editability [in] TRUE if text is editable by default 
Returns: 


whether text inserted at iter would be editable 


6.42.2.22 gint gtk_text_iter_compare (const GtkTextlter « lhs, const GtkTextlter * rhs) 
A qsort()-style function that returns negative if lhs is less than rhs, positive if lhs is greater than rhs, and 0 
if they’re equal. 


Ordering is in character offset order, i.e. the first character in the buffer is less than the second character in 
the buffer. 


Parameters: 


iter [in] a GtkTextlter 
iter [in] another GtkTextlIter 


Returns: 


-1 if lhs is less than rhs, 1 if Ihs is greater, O if they are equal 


6.42.2.23 GtkTextlterx gtk_text_iter_copy (const GtkTextIter x iter) 


Creates a dynamically-allocated copy of an iterator. 


This function is not useful in applications, because iterators can be copied with a simple assignment (Gtk- 
Textlter i =j;). The function is used by language bindings. 


Parameters: 
iter [in] an iterator 
Returns: 


a copy of the iter, free with gtk_text_iter_free() 
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6.42.2.24 gboolean gtk_text_iter_editable (const GtkTextIter « iter, gboolean default_setting) 


Returns whether the character at iter is within an editable region of text. 


Non-editable text is "locked" and can’t be changed by the user via GtkText View. This function is simply a 
convenience wrapper around gtk_text_iter_get_attributes(). If no tags applied to this text affect editability, 
default_setting will be returned. 


You don’t want to use this function to decide whether text can be inserted at iter, because for insertion you 
don’t want to know whether the char at iter is inside an editable range, you want to know whether a new 
character inserted at iter would be inside an editable range. Use gtk_text_iter_can_insert() to handle this 
case. 


Parameters: 
iter [in] an iterator 


default_setting [in] TRUE if text is editable by default 


Returns: 


whether iter is inside an editable range 


6.42.2.25 gboolean gtk_text_iter_ends_line (const GtkTextlter x iter) 


Returns TRUE if iter points to the start of the paragraph delimiter characters for a line (delimiters will 
be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph 
separator character). 


o 
nn nn 


Note that an iterator pointing to the newline char ("") of a carriage return/ newline ("") pair will not be 
counted as the end of a line, the line ends before the carriage return ("") . The end iterator is considered to 
be at the end of a line, even though there are no paragraph delimiter chars there. 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


whether iter is at the end of a line 


6.42.2.26 gboolean gtk_text_iter_ends_sentence (const GtkTextlter « iter) 


Determines whether iter ends a sentence. 

Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the 
correct fix would be to the Pango text boundary algorithms). 

Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if iter is at the end of a sentence. 
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6.42.2.27 gboolean gtk_text_iter_ends_tag (const GtkTextlter x iter, GtkTextTag x tag) 


Returns TRUE if tag is toggled off at exactly this point. 
If tag is NULL, returns TRUE if any tag is toggled off at this point. Note that the gtk_text_iter_ends_tag() 
returns TRUE if iter is the end of the tagged range; gtk_text_iter_has_tag() tells you whether an iterator is 
within a tagged range. 
Parameters: 

iter [in] an iterator 

tag [in] a GtkTextTag, or NULL 


Returns: 


whether iter is the end of a range tagged with tag 


6.42.2.28 gboolean gtk_text_iter_ends_word (const GtkTextlter « iter) 


Determines whether iter ends a natural-language word. 

Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix 
would be to the Pango word break algorithms). 

Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if iter is at the end of a word 


6.42.2.29 gboolean gtk_text_iter_forward_char (GtkTextlter x iter) 


Moves iter forward by one character offset. 


Note that images embedded in the buffer occupy 1 character slot, so gtk_text_iter_forward_char() may 
actually move onto an image instead of a character, if you have images in your buffer. If iter is the end 
iterator or one character before it, iter will now point at the end iterator, and gtk_text_iter_forward_char() 
returns FALSE for convenience when writing loops. 


Parameters: 


iter [in] an iterator 


Returns: 


whether iter moved and is dereferenceable 


6.42.2.30  gboolean gtk_text_iter_forward_chars (GtkTextlter x iter, gint count) 


Moves count characters if possible (if count would move past the start or end of the buffer, moves to the 
start or end of the buffer). 
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The return value indicates whether the new position of iter is different from its original position, and 
dereferenceable (the last iterator in the buffer is not dereferenceable). If count is 0, the function does 
nothing and returns FALSE. 


Parameters: 
iter [in] an iterator 


count [in] number of characters to move, may be negative 


Returns: 


whether iter moved and is dereferenceable 


6.42.2.31 gboolean gtk_text_iter_forward_cursor_position (GtkTextlter x iter) 


cursor positions are almost equivalent to chars, but not quite; in some languages, you can't put the cursor 
between certain chars. 


mon 


Also, you can’t put the cursor between carriage return/ newline char ("°") at the end of a line. 


Moves iter forward by a single cursor position. Cursor positions are (unsurprisingly) positions where the 
cursor can appear. Perhaps surprisingly, there may not be a cursor position between all characters. The 
most common example for European languages would be a carriage return/newline sequence. For some 
Unicode characters, the equivalent of say the letter "a" with an accent mark will be represented as two 
characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can’t 
go between those two characters. See also the PangoLogAttr structure and pango_break() function. 


Parameters: 


iter [in] an iterator 


Returns: 


TRUE if we moved and the new position is dereferenceable 


6.42.2.32 gboolean gtk_text_iter_forward_cursor_positions (GtkTextlter x iter, gint count) 


Moves up to count cursor positions. 


See gtk_text_iter_forward_cursor_position() for details. 


Parameters: 
iter [in] an iterator 


count [in] number of positions to move 


Returns: 


TRUE if we moved and the new position is dereferenceable 
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6.42.2.33 gboolean gtk_text_iter_forward_find_char (GtkTextlter x iter, GtkTextCharPredicate 
pred, gpointer user_data, const GtkTextlter x limit) 
Advances iter, calling pred on each character. 
If pred returns TRUE, returns TRUE and stops scanning. If pred never returns TRUE, iter is set to limit if 
limit is non-NULL, otherwise to the end iterator. 
Parameters: 
iter [in] a GtkTextlter 
pred [in] a function to be called on each character 
user_data [in] user data for pred 


limit [in] search limit, or NULL for none 


Returns: 


whether a match was found 


6.42.2.34 gboolean gtk_text_iter_forward_line (GtkTextlter x iter) 


Moves iter to the start of the next line. 

Returns TRUE if there was a next line to move to, and FALSE if iter was simply moved to the end of the 
buffer and is now not dereferenceable, or if iter was already at the end of the buffer. 

Parameters: 


iter [in] an iterator 


Returns: 


whether iter can be dereferenced 


6.42.2.35 gboolean gtk_text_iter_forward_lines (GtkTextlIter x iter, gint count) 
Moves count lines forward, if possible (if count would move past the start or end of the buffer, moves to 
the start or end of the buffer). 
The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t 
move, or moved onto the end iterator, then FALSE is returned. If count is 0, the function does nothing and 
returns FALSE. If count is negative, moves backward by 0 - count lines. 
Parameters: 

iter [in] an iterator 


count [in] number of lines to move forward 


Returns: 


whether iter moved and is dereferenceable 
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6.42.2.36 gboolean gtk_text_iter_forward_search (const GtkTextlter « iter, const gchar x str, 
GtkTextSearchFlags flags, GtkTextIter x match_start, GtkTextlter x match_end, const 
GtkTextIter x limit) 


Searches forward for str. 


Any match is returned by setting match_start to the first character of the match and match_end to the first 
character after the match. The search will not continue past limit. Note that a search is a linear or O(n) 
operation, so you may wish to use limit to avoid locking up your UI on large buffers. 


If the GTK_TEXT_SEARCH_VISIBLE_ONLY flag is present, the match may have invisible text inter- 
spersed in str. i.e. str will be a possibly-noncontiguous subsequence of the matched range. similarly, if you 
specify GTK_TEXT_SEARCH_TEXT_ONLY, the match may have pixbufs or child widgets mixed inside 
the matched range. If these flags are not given, the match must be exact; the special OxFFFC character in 
str will match embedded pixbufs or child widgets 


Parameters: 


iter [in] start of search 

str [in] a search string 

flags [in] flags affecting how the search is done 

match_start [out] return location for start of match, or NULL 
match_end [out] return location for end of match, or NULL 

limit [out] bound for the search, or NULL for the end of the buffer 


Returns: 


whether a match was found 


6.42.2.37 gboolean gtk_text_iter_forward_sentence_end (GtkTextlter + iter) 


Moves forward to the next sentence end. 


(If iter is at the end of a sentence, moves to the next end of sentence.) Sentence boundaries are determined 
by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango text 
boundary algorithms). 


Parameters: 


iter [in] an iterator 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.38 gboolean gtk_text_iter_forward_sentence_ends (GtkTextlter x iter, gint count) 


Calls gtk_text_iter_forward_sentence_end() count times (or until gtk_text_iter_forward_sentence_end() 
returns FALSE). 


If count is negative, moves backward instead of forward. 


Parameters: 


iter [in] an iterator 
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count [in] number of sentences to move 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.39 void gtk_text_iter_forward_to_end (GtkTextlter + iter) 


Moves iter forward to the "end iterator," which points one past the last valid character in the buffer. 


gtk_text_iter_get_char() called on the end iterator returns 0, which is convenient for writing loops. 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


void 


6.42.2.40 gboolean gtk_text_iter_forward_to_line_end (GtkTextlIter + iter) 
Moves the iterator to point to the paragraph delimiter characters, which will be either a newline, a carriage 
return, a carriage return/newline in sequence, or the Unicode paragraph separator character. 


If the iterator is already at the paragraph delimiter characters, moves to the paragraph delimiter characters 
for the next line. If iter is on the last line in the buffer, which does not end in paragraph delimiters, moves 
to the end iterator (end of the last line), and returns FALSE. 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if we moved and the new location is not the end iterator 


6.42.2.41 gboolean gtk_text_iter_forward_to_tag_toggle (GtkTextlter x iter, GtkTextTag + tag) 
Moves forward to the next toggle (on or off) of the GtkTextTag tag, or to the next toggle of any tag if tag is 
NULL. 


If no matching tag toggles are found, returns FALSE, otherwise TRUE. Does not return toggles located at 
iter, only toggles after iter. Sets iter to the location of the toggle, or to the end of the buffer if no toggle is 
found. 


Parameters: 

iter [in] an iterator 

tag [in] a GtkTextTag, or NULL 
Returns: 


whether we found a tag toggle after iter 
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6.42.2.42 gboolean gtk_text_iter_forward_visible_cursor_position (GtkTextlter x iter) 


Moves iter forward to the next visible cursor position. 


See gtk_text_iter_forward_cursor_position() for details. 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if we moved and the new position is dereferenceable 


6.42.2.43 gboolean gtk_text_iter_forward_visible_cursor_positions (GtkTextlIter x iter, gint count) 


Moves up to count visible cursor positions. 


See gtk_text_iter_forward_cursor_position() for details. 


Parameters: 


iter [in] a GtkTextlter 


count [in] number of positions to move 


Returns: 


TRUE if we moved and the new position is dereferenceable 


6.42.2.44 gboolean gtk_text_iter_forward_visible_line (GtkTextlter x iter) 


Moves iter to the start of the next visible line. 


Returns TRUE if there was a next line to move to, and FALSE if iter was simply moved to the end of the 
buffer and is now not dereferenceable, or if iter was already at the end of the buffer. 


Parameters: 


iter [in] an iterator 


Returns: 


whether iter can be dereferenced 


6.42.2.45 gboolean gtk_text_iter_forward_visible_lines (GtkTextlter x iter, gint count) 
Moves count visible lines forward, if possible (if count would move past the start or end of the buffer, 
moves to the start or end of the buffer). 


The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t 
move, or moved onto the end iterator, then FALSE is returned. If count is 0, the function does nothing and 
returns FALSE. If count is negative, moves backward by 0 - count lines. 


Parameters: 


iter [in] an iterator 
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count [in] number of lines to move forward 


Returns: 


whether iter moved and is dereferenceable 


6.42.2.46 gboolean gtk_text_iter_forward_visible_word_end (GtkTextlter x iter) 


Moves forward to the next visible word end. 


(If iter is currently on a word end, moves forward to the next one after that.) Word breaks are determined 
by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word 
break algorithms). 


Parameters: 


iter [in] an iterator 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.47 gboolean gtk_text_iter_forward_visible_word_ends (GtkTextlter « iter, gint count) 


Calls gtk_text_iter_forward_visible_word_end() up to count times. 


Parameters: 
iter [in] an iterator 


count [in] number of times to move 


Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.48 gboolean gtk_text_iter_forward_word_end (GtkTextlIter + iter) 


Moves forward to the next word end. 

(If iter is currently on a word end, moves forward to the next one after that.) Word breaks are determined 
by Pango and should be correct for nearly any language (if not, the correct fix would be to the Pango word 
break algorithms). 

Parameters: 


iter [in] an iterator 


Returns: 


TRUE if iter moved and is not the end iterator 
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6.42.2.49 gboolean gtk_text_iter_forward_word_ends (GtkTextlIter x iter, gint count) 


Calls gtk_text_iter_forward_word_end() up to count times. 


Parameters: 

iter [in] an iterator 

count [in] number of times to move 
Returns: 


TRUE if iter moved and is not the end iterator 


6.42.2.50 void gtk_text_iter_free (GtkTextlter x iter) 


Free an iterator allocated on the heap. 


This function is intended for use in language bindings, and is not especially useful for applications, because 
iterators can simply be allocated on the stack. 


Parameters: 


iter [in] a dynamically-allocated iterator 


Returns: 


void 


6.42.2.51 gboolean gtk_text_iter_get_attributes (const GtkTextlIter x iter, GtkTextAttributes x 
values) 
Computes the effect of any tags applied to this spot in the text. 


The values parameter should be initialized to the default settings you wish to use if no tags are in effect. 
You'd typically obtain the defaults from gtk_text_view_get_default_attributes(). 


gtk_text_iter_get_attributes() will modify values, applying the effects of any tags present at iter. If any tags 
affected values, the function returns TRUE. 


Parameters: 


iter [in] an iterator 
values [in] a GtkTextAttributes to be filled in 


Returns: 


TRUE if values was modified 


6.42.2.52 GtkTextBuffer* gtk_text_iter_get_buffer (const GtkTextlter x iter) 


Returns the GtkTextBuffer this iterator is associated with. 


Parameters: 


iter [in] an iterator 
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Returns: 


the buffer 


6.42.2.53 gint gtk_text_iter_get_bytes_in_line (const GtkTextIter + iter) 
Returns the number of bytes in the line containing iter, including the paragraph delimiters. 


Parameters: 


iter [in] an iterator 


Returns: 


number of bytes in the line 


6.42.2.54 gunichar gtk_text_iter_get_char (const GtkTextlter x iter) 


Returns the Unicode character at this iterator. 


(Equivalent to operator* on a C++ iterator.) If the element at this iterator is a non-character element, such 
as an image embedded in the buffer, the Unicode "unknown" character OxFFFC is returned. If invoked on 
the end iterator, zero is returned; zero is not a valid Unicode character. So you can write a loop which ends 
when gtk_text_iter_get_char() returns 0. 


Parameters: 


iter [in] an iterator 


Returns: 


a Unicode character, or 0 if iter is not dereferenceable 


6.42.2.55 gint gtk_text_iter_get_chars_in_line (const GtkTextlter « iter) 
Returns the number of characters in the line containing iter, including the paragraph delimiters. 


Parameters: 


iter [in] an iterator 


Returns: 


number of characters in the line 


6.42.2.56 GtkTextChildAnchorx gtk_text_iter_get_child_anchor (const GtkTextIter « iter) 


If the location at iter contains a child anchor, the anchor is returned (with no new reference count added). 


Otherwise, NULL is returned. 


Parameters: 


iter [in] an iterator 
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Returns: 


the anchor at iter 


6.42.2.57 PangoLanguagex gtk_text_iter_get_language (const GtkTextlter x iter) 


A convenience wrapper around gtk_text_iter_get_attributes(), which returns the language in effect at iter. 


If no tags affecting language apply to iter, the return value is identical to that of gtk_get_default_- 
language(). 


Parameters: 


iter [in] an iterator 


Returns: 


language in effect at iter 


6.42.2.58 gint gtk_text_iter_get_line (const GtkTextlIter x iter) 


Returns the line number containing the iterator. 


Lines in a GtkTextBuffer are numbered beginning with 0 for the first line in the buffer. 


Parameters: 


iter [in] an iterator 


Returns: 


a line number 


6.42.2.59 gint gtk_text_iter_get_line_index (const GtkTextlter x iter) 


Returns the byte index of the iterator, counting from the start of a newline-terminated line. 


Remember that GtkTextBuffer encodes text in UTF-8, and that characters can require a variable number of 
bytes to represent. 


Parameters: 


iter [in] an iterator 


Returns: 


distance from start of line, in bytes 


6.42.2.60 gint gtk_text_iter_get_line_offset (const GtkTextlter x iter) 


Returns the character offset of the iterator, counting from the start of a newline-terminated line. 


The first character on the line has offset 0. 
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Parameters: 


iter [in] an iterator 


Returns: 


offset from start of line 


6.42.2.61 GSListx* gtk_text_iter_get_marks (const GtkTextlter « iter) 


Returns a list of all GtkTextMark at this location. 


Because marks are not iterable (they don’t take up any "space" in the buffer, they are just marks in between 
iterable locations), multiple marks can exist in the same place. The returned list is not in any meaningful 
order. 


Parameters: 


iter [in] an iterator 


Returns: 


list of GtkTextMark 


6.42.2.62 gint gtk_text_iter_get_offset (const GtkTextlter « iter) 


Returns the character offset of an iterator. 


Each character in a GtkTextBuffer has an offset, starting with O for the first character in the buffer. Use 
gtk_text_buffer_get_iter_at_offset() to convert an offset back into an iterator. 


Parameters: 


iter [in] an iterator r 


Returns: 


a character offset 


6.42.2.63 GdkPixbufx gtk_text_iter_get_pixbuf (const GtkTextIter x iter) 


If the element at iter is a pixbuf, the pixbuf is returned (with no new reference count added). 


Otherwise, NULL is returned. 


Parameters: 


iter [in] an iterator 


Returns: 


the pixbuf at iter 
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6.42.2.64 gchar» gtk_text_iter_get_slice (const GtkTextlter x start, const GtkTextIter x end) 


Returns the text in the given range. 


A "slice" is an array of characters encoded in UTF-8 format, including the Unicode "unknown" character 
OxFFFC for iterable non-character elements in the buffer, such as images. Because images are encoded in 
the slice, byte and character offsets in the returned array will correspond to byte offsets in the text buffer. 
Note that OxFFFC can occur in normal text as well, so it is not a reliable indicator that a pixbuf or widget 
is in the buffer. 

Parameters: 


iter [in] iterator at start of a range 


iter [in] iterator at end of a range 


Returns: 


slice of text from the buffer 


6.42.2.65 GSList* gtk_text_iter_get_tags (const GtkTextlIter + iter) 


Returns a list of tags that apply to iter, in ascending order of priority (highest-priority tags are last). 


The GtkTextTag in the list don’t have a reference added, but you have to free the list itself. 


Parameters: 


iter [in] an iterator 


Returns: 


list of GtkTextTag 


6.42.2.66 gchar gtk_text_iter_get_text (const GtkTextIter x start, const GtkTextlter x end) 


Returns text in the given range. 
If the range contains non-text elements such as images, the character and byte offsets in the returned string 
will not correspond to character and byte offsets in the buffer. If you want offsets to correspond, see 
gtk_text_iter_get_slice(). 
Parameters: 

iter [in] iterator at start of a range 


iter [in] iterator at end of a range 


Returns: 


array of characters from the buffer 
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6.42.2.67 GSList« gtk_text_iter_get_toggled_tags (const GtkTextlter x iter, gboolean toggled_on) 


Returns a list of GtkTextTag that are toggled on or off at this point. 


(If toggled_on is TRUE, the list contains tags that are toggled on.) If a tag is toggled on at iter, then some 
non-empty range of characters following iter has that tag applied to it. If a tag is toggled off, then some 
non-empty range following iter does not have the tag applied to it. 


Parameters: 


iter [in] an iterator 


toggled_on [in] TRUE to get toggled-on tags 


Returns: 


tags toggled at this point 


6.42.2.68 gint gtk_text_iter_get_visible_line_index (const GtkTextlter x iter) 


Returns the number of bytes from the start of the line to the given iter, not counting bytes that are invisible 
due to tags with the "invisible" flag toggled on. 


Parameters: 


iter [in] an iterator 


Returns: 


byte index of iter with respect to the start of the line 


6.42.2.69 gint gtk_text_iter_get_visible_line_offset (const GtkTextlter x iter) 


Returns the offset in characters from the start of the line to the given iter, not counting characters that are 
invisible due to tags with the "invisible" flag toggled on. 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


offset in visible characters from the start of the line 


6.42.2.70 gchar gtk_text_iter_get_visible_slice (const GtkTextIter x start, const GtkTextlter + 
end) 
Like gtk_text_iter_get_slice(), but invisible text is not included. 


Invisible text is usually invisible because a GtkTextTag with the "invisible" attribute turned on has been 
applied to it. 


Parameters: 


iter [in] an iterator 
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iter [in] an iterator 


Returns: 


byte index of iter with respect to the start of the line 


6.42.2.71 gchar gtk_text_iter_get_visible_text (const GtkTextlter x start, const GtkTextlter « end) 


Returns the number of bytes from the start of the line to the given iter, not counting bytes that are invisible 
due to tags with the "invisible" flag toggled on. 


Parameters: 
iter [in] iterator at start of range 


iter [in] iterator at end of range 


Returns: 


slice of text from the buffer 


6.42.2.72 gboolean gtk_text_iter_has_tag (const GtkTextlter x iter, GtkTextTag « tag) 


Returns TRUE if iter is within a range tagged with tag. 


Parameters: 
iter [in] an iterator 


tag [in] a GtkTextTag 


Returns: 


whether iter is tagged with tag 


6.42.2.73 gboolean gtk_text_iter_in_range (const GtkTextlter x iter, const GtkTextlter x start, 
const GtkTextlter x end) 
Checks whether iter falls in the range [start, end). 


start and end must be in ascending order. 


Parameters: 
iter [in] a GtkTextlter 
start [in] start of range 


end [in] end of range 


Returns: 


TRUE if iter is in the range 
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6.42.2.74 gboolean gtk_text_iter_inside_sentence (const GtkTextIter + iter) 


Determines whether iter is inside a sentence (as opposed to in between two sentences, e.g. 


after a period and before the first letter of the next sentence). Sentence boundaries are determined by Pango 
and should be correct for nearly any language (if not, the correct fix would be to the Pango text boundary 
algorithms). 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if iter is inside a sentence. 


6.42.2.75 gboolean gtk_text_iter_inside_word (const GtkTextlIter « iter) 


Determines whether iter is inside a natural-language word (as opposed to say inside some whitespace). 


Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix 
would be to the Pango word break algorithms). 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if iter is inside a word 


6.42.2.76 gboolean gtk_text_iter_is_cursor_position (const GtkTextlter + iter) 


See gtk_text_iter_forward_cursor_position() or PangoLogAttr or pango_break() for details on what a cur- 
sor position is. 


Parameters: 
iter [in] a GtkTextlter 
Returns: 


TRUE if the cursor can be placed at iter 


6.42.2.77 gboolean gtk_text_iter_is_end (const GtkTextlter x iter) 


Returns TRUE if iter is the end iterator, i.e. 


one past the last dereferenceable iterator in the buffer. gtk_text_iter_is_end() is the most efficient way to 
check whether an iterator is the end iterator. 


Parameters: 
iter [in] an iterator 
Returns: 


whether iter is the end iterator 
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6.42.2.78 gboolean gtk_text_iter_is_start (const GtkTextlter x iter) 
Returns TRUE if iter is the first iterator in the buffer, that is if iter has a character offset of 0. 


Parameters: 


iter [in] an iterator 


Returns: 


whether iter is the first in the buffer 


6.42.2.79 void gtk_text_iter_order (GtkTextlIter x first, GtkTextIter * second) 


Swaps the value of first and second if second comes before first in the buffer. 


That is, ensures that first and second are in sequence. Most text buffer functions that take a range call this 
automatically on your behalf, so there’s no real reason to call it yourself in those cases. There are some 
exceptions, such as gtk_text_iter_in_range(), that expect a pre-sorted range. 


Parameters: 


iter [in] a GtkTextlter 
second [in] another GtkTextlter 


Returns: 


void 


6.42.2.80 void gtk_text_iter_set_line (GtkTextIter x iter, gint line_number) 


Moves iterator iter to the start of the line line_number. 


If line_number is negative or larger than the number of lines in the buffer, moves iter to the start of the last 
line in the buffer. 


Parameters: 


iter [in] a GtkTextlter 


line_number [in] line number (counted from 0) 


Returns: 


void 


6.42.2.81 void gtk_text_iter_set_line_index (GtkTextlIter x iter, gint byte_on_line) 


Same as gtk_text_iter_set_line_offset(), but works with a byte index. 


The given byte index must be at the start of a character, it can’t be in the middle of a UTF-8 encoded 
character. 


Parameters: 


iter [in] a GtkTextlter 
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byte_on_line [in] a byte index relative to the start of iter’s current line 


Returns: 


void 


6.42.2.82 void gtk_text_iter_set_line_offset (GtkTextlter x iter, gint char_on_line) 


Moves iter within a line, to a new character (not byte) offset. 


The given character offset must be less than or equal to the number of characters in the line; if equal, iter 
moves to the start of the next line. See gtk_text_iter_set_line_index() if you have a byte index rather than 
a character offset. 


Parameters: 


iter [in] a GtkTextlter 


iter [in] a character offset relative to the start of iter’s current line 


Returns: 


void 


6.42.2.83 void gtk_text_iter_set_offset (GtkTextIter x iter, gint char_offset) 


Sets iter to point to char_offset. 


char_offset counts from the start of the entire text buffer, starting with 0. 


Parameters: 


iter [in] a GtkTextlter 


char_offset [in] a character number 


Returns: 


void 


6.42.2.84 void gtk_text_iter_set_visible_line_index (GtkTextlter « iter, gint byte_on_line) 


Like gtk_text_iter_set_line_index(), but the index is in visible bytes, 1.e. 


text with a tag making it invisible is not counted in the index. 


Parameters: 


iter [in] a GtkTextlter 


byte_on_line [in] a byte index 


Returns: 


void 
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6.42.2.85 void gtk_text_iter_set_visible_line_offset (GtkTextIter x iter, gint char_on_line) 


Like gtk_text_iter_set_line_offset(), but the offset is in visible characters, i.e. 


text with a tag making it invisible is not counted in the offset. 


Parameters: 


iter [in] a GtkTextlter 


char_on_line [in] a character offset 


Returns: 


void 


6.42.2.86 gboolean gtk_text_iter_starts_line (const GtkTextlter x iter) 


Returns TRUE if iter begins a paragraph, i.e. 


if gtk_text_iter_get_line_offset() would return 0. However this function is potentially more efficient than 
gtk_text_iter_get_line_offset() because it doesn’t have to compute the offset, it just has to see whether it’s 
0. 


Parameters: 


iter [in] an iterator 


Returns: 


whether iter begins a line 


6.42.2.87 gboolean gtk_text_iter_starts_sentence (const GtkTextlter x iter) 


Determines whether iter begins a sentence. 


Sentence boundaries are determined by Pango and should be correct for nearly any language (if not, the 
correct fix would be to the Pango text boundary algorithms). 


Parameters: 


iter [in] a GtkTextlter 


Returns: 


TRUE if iter is at the start of a sentence 


6.42.2.88 gboolean gtk_text_iter_starts_word (const GtkTextlter x iter) 


Determines whether iter begins a natural-language word. 

Word breaks are determined by Pango and should be correct for nearly any language (if not, the correct fix 
would be to the Pango word break algorithms). 

Parameters: 


iter [in] a GtkTextlter 
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Returns: 


TRUE if iter is at the start of a word 


6.42.2.89 gboolean gtk_text_iter_toggles_tag (const GtkTextlter x iter, GtkTextTag + tag) 


This is equivalent to (gtk_text_iter_begins_tag() || gtk_text_iter_ends_tag()), i.e. 


it tells you whether a range with tag applied to it begins or ends at iter. 


Parameters: 


iter [in] an iterator 
tag [in] a GtkTextTag, or NULL 


Returns: 


whether tag is toggled on or off at iter 
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6.43 GtkTextMark 


6.43.1 Detailed Description 


A position in the buffer preserved across buffer modifications. 


You may wish to begin by reading the text widget conceptual overview which gives an overview of all the 
objects and data types related to the text widget and how they work together. 


A GtkTextMark is like a bookmark in a text buffer; it preserves a position in the text. You can convert the 
mark to an iterator using gtk_text_buffer_get_iter_at_mark(). Unlike iterators, marks remain valid across 
buffer mutations, because their behavior is defined when text is inserted or deleted. When text containing 
a mark is deleted, the mark remains in the position originally occupied by the deleted text. When text is 
inserted at a mark, a mark with left gravity will be moved to the beginning of the newly-inserted text, and 
a mark with right gravity will be moved to the end. 


Marks are reference counted, but the reference count only controls the validity of the memory; marks can 
be deleted from the buffer at any time with gtk_text_buffer_delete_mark(). Once deleted from the buffer, a 
mark is essentially useless. 


Marks optionally have names; these can be convenient to avoid passing the GtkTextMark object around. 


Marks are typically created using the gtk_text_buffer_create_mark() function. 


Data Structures 


¢ struct _GtkTextMark 


GtkTextMark instance structure. 


e struct _GtkTextMarkClass 


GtkTextMark instance class structure. 


Functions 


e void gtk_text_mark_set_visible (GtkTextMark «mark, gboolean setting) 


Sets the visibility of mark; the insertion point is normally visible, i.e. 


e gboolean gtk_text_mark_get_visible (GtkTextMark *mark) 
Returns TRUE if the mark is visible (i.e. 


G_CONST_RETURN gchar x gtk_text_mark_get_name (GtkTextMark *mark) 


Returns the mark name; returns NULL for anonymous marks. 


e gboolean gtk_text_mark_get_deleted (GtkTextMark *mark) 
Returns TRUE if the mark has been removed from its buffer with gtk_text_buffer_delete_mark(). 


GtkTextBuffer x gtk_text_mark_get_buffer (GtkTextMark *mark) 
Gets the buffer this mark is located inside, or NULL if the mark is deleted. 


e gboolean gtk_text_mark_get_left_gravity (GtkTextMark *mark) 


Determines whether the mark has left gravity. 
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6.43.2 Function Documentation 
6.43.2.1 GtkTextBufferx gtk_text_mark_get_buffer (GtkTextMark x mark) 
Gets the buffer this mark is located inside, or NULL if the mark is deleted. 


Parameters: 


mark [in] a GtkTextMark 


Returns: 


the mark’s GtkTextBuffer 


6.43.2.2 gboolean gtk_text_mark_get_deleted (GtkTextMark x mark) 


Returns TRUE if the mark has been removed from its buffer with gtk_text_buffer_delete_mark(). 


Marks can’t be used once deleted. 


Parameters: 


mark [in] a GtkTextMark 


Returns: 


whether the mark is deleted 


6.43.2.3 gboolean gtk_text_mark_get_left_gravity (GtkTextMark x mark) 


Determines whether the mark has left gravity. 


Parameters: 


mark [in] a GtkTextMark 


Returns: 


TRUE if the mark has left gravity, FALSE otherwise 


6.43.2.4 G CONST_RETURN gchar» gtk_text_mark_get_name (GtkTextMark x mark) 


Returns the mark name; returns NULL for anonymous marks. 


Parameters: 


mark [in] a GtkTextMark 


Returns: 


mark name 
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6.43.2.5  gboolean gtk_text_mark_get_ visible (GtkTextMark x mark) 


Returns TRUE if the mark is visible (i.e. 


a cursor is displayed for it) 


Parameters: 


mark [in] a GtkTextMark 


Returns: 


TRUE if visible 


6.43.2.6 void gtk_text_mark_set_visible (GtkTextMark * mark, gboolean setting) 


Sets the visibility of mark; the insertion point is normally visible, 1.e. 

you can see it as a vertical bar. Also, the text widget uses a visible mark to indicate where a drop will occur 
when dragging-and-dropping text. Most other marks are not visible. Marks are not visible by default. 
Parameters: 


mark [in] a GtkTextMark 


setting [in] visibility of mark 


Returns: 


void 
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6.44 GtkTextBuffer 


6.44.1 Detailed Description 


This file defines the functions of GtkTextBuffer. 


You may wish to begin by reading the text widget conceptual overview which gives an overview of all the 
objects and data types related to the text widget and how they work together. 


Code Example 


GtkTextBuffer x*buffer; 
GtkWidget *text_view; 
GtkWidget «sw; 


sw = gtk_scrolled_window_new (NULL, NULL); 
gtk_scrolled_window_set_shadow_type (GTK_SCROLLED_WINDOW (sw), 
GTK_SHADOW_ IN); 


text_view = gtk_text_view_new (); 
gtk_widget_set_size_request (text_view, 400, 300); 
gtk_container_add (GTK_CONTAINER (sw), text_view); 
buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (text_view)); 
gtk_text_buffer_set_text (buffer, 
"In felaweshipe, and pilgrimes were they alle, \n" 
"That toward Caunterbury wolden ryde.\n" 
"The chambres and the stables weren wyde, \n" 
"And wel we weren esed atte beste; \n" 
"And shortly, whan the sonne was to reste, \n" 
Wr 
"So hadde I spoken with hem everychon \n" 
"That I was of hir felaweshipe anon, \n" 
"And made forward erly for to ryse \n" 
"To take our wey, ther as I yow devyse. \n" 
NE But nathelees, whil I have tyme and space, An" 
" \n" 
"Er that I ferther in this tale pace, An" 
"Me thynketh it acordaunt to resoun \n" 
"To telle yow al the condicioun \n" 
"Of ech of hem, so as it semed me, \n" 
"And whiche they weren, and of what degree, \n" 
" An" 
"And eek in what array that they were inne; An" 
"And at a knyght than wol 1 first bigynne. An" 
m A knyght ther was, and that a worthy man, \n" 
"That fro the tyme that he first bigan \n" 
"To riden out, he loved chivalrie, \n" 
" Aa 
"Trouthe and honour, fredom and curteisie. An" 
"Ful worthy was he in his lordes werre, An" 
" \n" 
"And therto hadde he riden, no man ferre, \n" 
"As wel in Cristendom as in Hethenesse, \n" 
"And evere honoured for his worthynesse. \n" 
" \n" 
" At Alisaundre he was, whan it was wonne; An" 
"Ful ofte tyme he hadde the bord bigonne \n" 
"Aboven alle nacions in Pruce; \n" 
"In Lettow hadde he reysed, and in Ruce, An" 
"No cristen man so ofte of his degree. \n", 
=1)5 
gtk_widget_show(text_view); 
gtk_widget_show (sw) ; 
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Data Structures 


struct _GtkTextBuffer 


GtkTextBuffer instance structure. 


struct _GtkTextBufferClass 


GtkTextBuffer instance class structure. 


Functions 


GtkTextBuffer x gtk_text_buffer_new (GtkTextTagTable *table) 


Creates a new text buffer. 


gint gtk_text_buffer_get_line_count (GtkTextBuffer «buffer) 


Obtains the number of lines in the buffer. 


gint gtk_text_buffer_get_char_count (GtkTextBuffer *buffer) 


Gets the number of characters in the buffer; note that characters and bytes are not the same, you can’t e.g. 


GtkTextTagTable « gtk_text_buffer_get_tag_table (GtkTextBuffer *buffer) 
Get the GtkTextTagTable associated with this buffer. 


void gtk_text_buffer_set_text (GtkTextBuffer «buffer, const gchar «text, gint len) 


Deletes current contents of buffer, and inserts text instead. 


void gtk_text_buffer_insert (GtkTextBuffer «buffer, GtkTextlter «iter, const gchar «text, gint len) 


Inserts len bytes of text at position iter. 


void gtk_text_buffer_insert_at_cursor (GtkTextBuffer «buffer, const gchar «text, gint len) 


Simply calls gtk_text_buffer_insert(), using the current cursor position as the insertion point. 


gboolean gtk_text_buffer_insert_interactive (GtkTextBuffer «buffer, GtkTextlter xiter, const gchar 
*text, gint len, gboolean default_editable) 


Like gtk_text_buffer_insert(), but the insertion will not occur if iter is at a non-editable location in the buffer. 


gboolean gtk_text_buffer_insert_interactive_at_cursor (GtkTextBuffer *buffer, const gchar text, 
gint len, gboolean default_editable) 


Calls gtk_text_buffer_insert_interactive() at the cursor position. 


void gtk_text_buffer_insert_range (GtkTextBuffer «buffer, GtkTextlter xiter, const GtkTextlter 
«start, const GtkTextlter *end) 


Copies text, tags, and pixbufs between start and end (the order of start and end doesn’t matter) and inserts 
the copy at iter. 


gboolean gtk_text_buffer_insert_range_interactive (GtkTextBuffer «buffer, GtkTextlter xiter, const 
GtkTextlter «start, const GtkTextIter «end, gboolean default_editable) 


Same as gtk_text_buffer_insert_range(), but does nothing if the insertion point isn’t editable. 
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e void gtk_text_buffer_insert_with_tags (GtkTextBuffer «buffer, GtkTextlter xiter, const gchar «text, 
gint len, GtkTextTag x*first_tag,...) G_GNUC_NULL_TERMINATED 


Inserts text into buffer at iter, applying the list of tags to the newly-inserted text. 


e void gtk_text_buffer_insert_with_tags_by_name (GtkTextBuffer «buffer, GtkTextlter xiter, const 
gchar *text, gint len, const gchar «first_tag_name,...) G_LGNUC_NULL_TERMINATED 


Same as gtk_text_buffer_insert_with_tags(), but allows you to pass in tag names instead of tag objects. 


e void gtk_text_buffer_delete (GtkTextBuffer «buffer, GtkTextlter «start, GtkTextlter *end) 


Deletes text between start and end. 


e gboolean gtk_text_buffer_delete_interactive (GtkTextBuffer «buffer, GtkTextlter *start_iter, Gtk- 
Textlter xend_iter, gboolean default_editable) 


Deletes all editable text in the given range. 


e gboolean gtk_text_buffer_backspace (GtkTextBuffer «buffer, GtkTextlter «iter, gboolean interactive, 
gboolean default_editable) 
Performs the appropriate action as if the user hit the delete key with the cursor at the position specified by 


iter. 


e gchar x gtk_text_buffer_get_text (GtkTextBuffer «buffer, const GtkTextlter «start, const GtkTextlter 
*end, gboolean include_hidden_chars) 


Returns the text in the range [start,end). 


e gchar x gtk_text_buffer_get_slice (GtkTextBuffer «buffer, const GtkTextlter *start, const GtkTextlter 
*end, gboolean include_hidden_chars) 


Returns the text in the range [start,end). 


e void gtk_text_buffer_insert_pixbuf (GtkTextBuffer «buffer, GtkTextlter «iter, GdkPixbuf *pixbuf) 


Inserts an image into the text buffer at iter. 


e void gtk_text_buffer_insert_child_anchor (GtkTextBuffer «buffer, GtkTextIter iter, Gtk- 
TextChildAnchor *anchor) 


Inserts a child widget anchor into the text buffer at iter. 


e GtkTextChildAnchor * gtk_text_buffer_create_child_anchor (GtkTextBuffer «buffer, GtkTextlter 
xiter) 


This is a convenience function which simply creates a child anchor with gtk_text_child_anchor_new() and 
inserts it into the buffer with gtk_text_buffer_insert_child_anchor(). 


e GtkTextMark « gtk_text_buffer_create_mark (GtkTextBuffer xbuffer, const gchar *mark_name, 
const GtkTextIter xwhere, gboolean left_gravity) 


Creates a mark at position where. 


e void gtk_text_buffer_move_mark (GtkTextBuffer xbuffer, GtkTextMark *mark, const GtkTextlter 
*where) 


Moves mark to the new location where. 


e void gtk_text_buffer_delete_mark (GtkTextBuffer «buffer, GtkTextMark *mark) 


Deletes mark, so that it’s no longer located anywhere in the buffer. 
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GtkTextMark « gtk_text_buffer_get_mark (GtkTextBuffer «buffer, const gchar xname) 


Returns the mark named name in buffer buffer, or NULL if no such mark exists in the buffer. 


void gtk_text_buffer_move_mark_by_name (GtkTextBuffer «buffer, const gchar xname, const Gtk- 
Textlter *where) 


Moves the mark named name (which must exist) to location where. 


void gtk_text_buffer_delete_mark_by_name (GtkTextBuffer «buffer, const gchar xname) 


Deletes the mark named name; the mark must exist. 


GtkTextMark « gtk_text_buffer_get_insert (GtkTextBuffer «buffer) 


Returns the mark that represents the cursor (insertion point). 


GtkTextMark « gtk_text_buffer_get_selection_bound (GtkTextBuffer «buffer) 


Returns the mark that represents the selection bound. 


void gtk_text_buffer_place_cursor (GtkTextBuffer «buffer, const GtkTextlter *where) 


This function moves the "insert" and "selection_bound" marks simultaneously. 


void gtk_text_buffer_select_range (GtkTextBuffer «buffer, const GtkTextlter «ins, const GtkTextlter 
*bound) 


This function moves the "insert" and "selection_bound" marks simultaneously. 


void gtk_text_buffer_apply_tag (GtkTextBuffer «buffer, GtkTextTag *tag, const GtkTextlter «start, 
const GtkTextlter xend) 


Emits the "apply_tag" signal on buffer. 


void gtk_text_buffer_remove_tag (GtkTextBuffer «buffer, GtkTextTag «tag, const GtkTextlter «start, 
const GtkTextlter *end) 


Emits the "remove_tag" signal. 


void gtk _text_buffer_apply_tag_by_name (GtkTextBuffer «buffer, const gchar xname, const Gtk- 
Textlter «start, const GtkTextlter *end) 


Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a GtkTextTag, then calls gtk_text_buffer_- 
apply_tag(). 


void gtk_text_buffer_remove_tag_by_name (GtkTextBuffer *buffer, const gchar xname, const Gtk- 
Textlter *start, const GtkTextlter x*end) 


Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a GtkTextTag, then calls gtk_text_buffer_- 
remove_tag(). 


void gtk_text_buffer_remove_all_tags (GtkTextBuffer «buffer, const GtkTextlter «start, const Gtk- 
Textlter *end) 


Removes all tags in the range between start and end. 


GtkTextTag * gtk_text_buffer_create_tag (GtkTextBuffer «buffer, const gchar *tag_name, const 
gchar x*first_property_name.,...) 


Creates a tag and adds it to the tag table for buffer. 


void gtk_text_buffer_get_iter_at_line_offset (GtkTextBuffer «buffer, GtkTextlter xiter, gint line_- 
number, gint char_offset) 
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Obtains an iterator pointing to char_offset within the given line. 


e void gtk text_buffer_get_iter_at_line_index (GtkTextBuffer «buffer, GtkTextlter x*iter, gint line_- 
number, gint byte_index) 


Obtains an iterator pointing to byte_index within the given line. 


e void gtk_text_buffer_get_iter_at_offset (GtkTextBuffer «buffer, GtkTextlter xiter, gint char_offset) 


Initializes iter to a position char_offset chars from the start of the entire buffer. 


e void gtk_text_buffer_get_iter_at_line (GtkTextBuffer «buffer, GtkTextlter xiter, gint line_number) 


Initializes iter to the start of the given line. 


e void gtk_text_buffer_get_start_iter (GtkTextBuffer «buffer, GtkTextlter xiter) 


Initialized iter with the first position in the text buffer. 


e void gtk_text_buffer_get_end_iter (GtkTextBuffer «buffer, GtkTextlter iter) 


Initializes iter with the "end iterator," one past the last valid character in the text buffer. 


e void gtk_text_buffer_get_bounds (GtkTextBuffer «buffer, GtkTextlter «start, GtkTextlter end) 


Retrieves the first and last iterators in the buffer, i.e. 


e void gtk_text_buffer_get_iter_at_mark (GtkTextBuffer buffer, GtkTextlter xiter, GtkTextMark 
*«mark) 


Initializes iter with the current position of mark. 


e void gtk_text_buffer_get_iter_at_child_anchor (GtkTextBuffer *buffer, GtkTextlter xiter, Gtk- 
TextChildAnchor *anchor) 


Obtains the location of anchor within buffer. 


e gboolean gtk_text_buffer_get_modified (GtkTextBuffer «buffer) 


Indicates whether the buffer has been modified since the last call to gtk_text_buffer_set_modified() set the 
modification flag to FALSE. 


e void gtk_text_buffer_set_modified (GtkTextBuffer «buffer, gboolean setting) 


Used to keep track of whether the buffer has been modified since the last time it was saved. 


e gboolean gtk_text_buffer_get_has_selection (GtkTextBuffer «buffer) 


Indicates whether the buffer has some text currently selected. 


e void gtk_text_buffer_add_selection_clipboard (GtkTextBuffer +buffer, GtkClipboard *clipboard) 


Adds clipboard to the list of clipboards in which the selection contents of buffer are available. 


e void gtk text_buffer_remove_selection_clipboard (GtkTextBuffer buffer,  GtkClipboard 
*clipboard) 


Removes a GtkClipboard added with gtk_text_buffer_add_selection_clipboard(). 


e void gtk_text_buffer_cut_clipboard (GtkTextBuffer «buffer, GtkClipboard clipboard, gboolean 
default_editable) 


Copies the currently-selected text to a clipboard, then deletes said text if it’s editable. 
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e void gtk_text_buffer_copy_clipboard (GtkTextBuffer *buffer, GtkClipboard *clipboard) 


Copies the currently-selected text to a clipboard. 


e void gtk_text_buffer_paste_clipboard (GtkTextBuffer *buffer, GtkClipboard *clipboard, GtkTextlter 


*overtride_location, gboolean default_editable) 


Pastes the contents of a clipboard at the insertion point, or at override_location. 


e gboolean gtk_text_buffer_get_selection_bounds (GtkTextBuffer «buffer, GtkTextlter «start, GtkTex- 


tIter xend) 


Returns TRUE if some text is selected; places the bounds of the selection in start and end (if the selection 
has length 0, then start and end are filled in with the same value). 


e gboolean gtk_text_buffer_delete_selection (GtkTextBuffer «buffer, gboolean interactive, gboolean 


default_editable) 


Deletes the range between the "insert" and "selection_bound" marks, that is, the currently-selected text. 


e void gtk_text_buffer_begin_user_action (GtkTextBuffer «buffer) 


Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() 
are part of a single user-visible operation. 


e void gtk_text_buffer_end_user_action (GtkTextBuffer «buffer) 


Should be paired with a call to gtk_text_buffer_begin_user_action(). 


e GtkTargetList x gtk_text_buffer_get_copy_target_list (GtkTextBuffer *buffer) 


This function returns the list of targets this text buffer can provide for copying and as DND source. 


e GtkTargetList « gtk_text_buffer_get_paste_target_list (GtkTextBuffer «buffer) 


This function returns the list of targets this text buffer supports for pasting and as DND destination. 


6.44.2 Function Documentation 


6.44.2.1 void gtk_text_buffer_add_selection_clipboard (GtkTextBuffer x buffer, GtkClipboard x 


clipboard) 


Adds clipboard to the list of clipboards in which the selection contents of buffer are available. 


In most cases, clipboard will be the GtkClipboard of type GDK_SELECTION_PRIMARY for a view of 
buffer. 


Parameters: 


buffer [in] a GtkTextBuffer 
clipboard [in] a GtkClipboard 


Returns: 


void 
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6.44.2.2 void gtk_text_buffer_apply_tag (GtkTextBuffer « buffer, GtkTextTag « tag, const 
GtkTextIter x start, const GtkTextIter « end) 


Emits the "apply_tag" signal on buffer. 


The default handler for the signal applies tag to the given range. start and end do not have to be in order. 


Parameters: 
buffer [in] a GtkTextBuffer 
tag [in] a GtkTextTag 
start [in] one bound of range to be tagged 


end [in] other bound of range to be tagged 


Returns: 


void 


6.44.2.3 void gtk_text_buffer_apply_tag_by_name (GtkTextBuffer « buffer, const gchar « name, 
const GtkTextIter x start, const GtkTextIter « end) 


Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a GtkTextTag, then calls gtk_text_buffer_- 
apply_tag(). 
Parameters: 


buffer [in] a GtkTextBuffer 
name [in] name of a named GtkTextTag 
start [in] one bound of range to be untagged 


end [in] other bound of range to be untagged 


Returns: 


void 


6.44.2.4 gboolean gtk_text_buffer_backspace (GtkTextBuffer x buffer, GtkTextIter x iter, 
gboolean interactive, gboolean default_editable) 


Performs the appropriate action as if the user hit the delete key with the cursor at the position specified by 
iter. 


In the normal case a single character will be deleted, but when combining accents are involved, more than 
one character can be deleted, and when precomposed character and accent combinations are involved, less 
than one character will be deleted. 


Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, 
the iter will be re-initialized to point to the location where text was deleted. 
Parameters: 


buffer [in] a GtkTextBuffer 


iter [in] a position in buffer 
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interactive [in] whether the deletion is caused by user interaction 
default_editable [in] whether the buffer is editable by default 


Returns: 


TRUE if the buffer was modified 


6.44.2.5 void gtk_text_buffer_begin_user_action (GtkTextBuffer x buffer) 


Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() 
are part of a single user-visible operation. 


The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can 
then be grouped when creating an undo stack. GtkTextBuffer maintains a count of calls to gtk_text_buffer_- 
begin_user_action() that have not been closed with a call to gtk_text_buffer_end_user_action(), and emits 
the "begin_user_action" and "end_user_action" signals only for the outermost pair of calls. This allows 
you to build user actions from other user actions. The "interactive" buffer mutation functions, such as 
gtk_text_buffer_insert_interactive(), automatically call begin/end user action around the buffer operations 
they perform, so there’s no need to add extra calls if you user action consists solely of a single call to one 
of those functions. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


void 


6.44.2.6 void gtk_text_buffer_copy_clipboard (GtkTextBuffer x buffer, GtkClipboard x clipboard) 


Copies the currently-selected text to a clipboard. 


Parameters: 


buffer [in] a GtkTextBuffer 
clipboard [in] the GtkClipboard object to copy to.s 


Returns: 


void 


6.44.2.7 GtkTextChildAnchor« gtk_text_buffer_create_child_anchor (GtkTextBuffer x buffer, 
GtkTextIter x iter) 


This is a convenience function which simply creates a child anchor with gtk_text_child_anchor_new() and 
inserts it into the buffer with gtk_text_buffer_insert_child_anchor(). 


The new anchor is owned by the buffer; no reference count is returned to the caller of gtk_text_buffer_- 
create_child_anchor(). 


Parameters: 


buffer [in] a GtkTextBuffer 
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iter [in] location in the buffer 


Returns: 


the created child anchor 


6.44.2.8 GtkTextMarkx gtk_text_buffer_create_mark (GtkTextBuffer x buffer, const gchar x 
mark_name, const GtkTextIter x where, gboolean left_gravity) 


Creates a mark at position where. 


If mark_name is NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using 
gtk_text_buffer_get_mark(). If a mark has left gravity, and text is inserted at the mark’s current location, 
the mark will be moved to the left of the newly-inserted text. If the mark has right gravity (left_gravity 
= FALSE), the mark will end up on the right of newly-inserted text. The standard left-to-right cursor is a 
mark with right gravity (when you type, the cursor stays on the right side of the text you’re typing). The 
caller of this function does not own a reference to the returned GtkTextMark, so you can ignore the return 
value if you like. Marks are owned by the buffer and go away when the buffer does. Emits the "mark_set" 
signal as notification of the mark’s initial placement. 


Parameters: 


buffer [in] a GtkTextBuffer 
mark_name [in] name for mark, or NULL 
where [in] location to place mark 


left_gravity [in] whether the mark has left gravity 


Returns: 


the new GtkTextMark object 


6.44.2.9 GtkTextTag* gtk_text_buffer_create_tag (GtkTextBuffer x buffer, const gchar x 
tag_name, const gchar x first_property_name, ...) 


Creates a tag and adds it to the tag table for buffer. 


Equivalent to calling gtk_text_tag_new() and then adding the tag to the buffer’s tag table. The returned tag 
is owned by the buffer’s tag table, so the ref count will be equal to one.If tag_name is NULL, the tag is 
anonymous. If tag_name is non-NULL, a tag called tag_name must not already exist in the tag table for 
this buffer. The first_property_name argument and subsequent arguments are a list of properties to set on 
the tag, as with g_object_set(). 


Parameters: 


buffer [in] a GtkTextBuffer 
tag_name [in] name of the new tag, or NULL 
first_property_name [in] name of first property to set, or NULL 


. [in] NULL-terminated list of property names and values 


Returns: 


a new tag 
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6.44.2.10 void gtk_text_buffer_cut_clipboard (GtkTextBuffer x buffer, GtkClipboard * clipboard, 
gboolean default_editable) 


Copies the currently-selected text to a clipboard, then deletes said text if it’s editable. 


Parameters: 


buffer [in] a GtkTextBuffer 
clipboard [in] the GtkClipboard object to cut to. 
default_editables [in] default editability of the buffer 


Returns: 


void 


6.44.2.11 void gtk_text_buffer_delete (GtkTextBuffer x buffer, GtkTextIter x start, GtkTextlter x 
end) 
Deletes text between start and end. 


The order of start and end is not actually relevant; gtk_text_buffer_delete() will reorder them. This function 
actually emits the "delete_range" signal, and the default handler of that signal deletes the text. Because the 
buffer is modified, all outstanding iterators become invalid after calling this function; however, the start 
and end will be re-initialized to point to the location where text was deleted. 
Parameters: 

buffer [in] a GtkTextBuffer 

start [in] a position in buffer 


end [in] another position in buffer 


Returns: 


void 


6.44.2.12 gboolean gtk_text_buffer_delete_interactive (GtkTextBuffer x buffer, GtkTextIter x 
start_iter, GtkTextlter x end_iter, gboolean default_editable) 


Deletes all editable text in the given range. 

Calls gtk_text_buffer_delete() for each editable sub-range of [start,end). start and end are revalidated to 
point to the location of the last deleted range, or left untouched if no text was deleted. 

Parameters: 


buffer [in] a GtkTextBuffer 

start_iter [in] start of range to delete 

end_iter [in] end of range 

default_editable [in] whether the buffer is editable by default 


Returns: 


whether some text was actually deleted 
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6.44.2.13 void gtk_text_buffer_delete_mark (GtkTextBuffer x buffer, GtkTextMark x mark) 


Deletes mark, so that it’s no longer located anywhere in the buffer. 


Removes the reference the buffer holds to the mark, so 1f you haven't called g_object_ref() on the mark, 
it will be freed. Even if the mark isn’t freed, most operations on mark become invalid. There is no way 
to undelete a mark. gtk_text_mark_get_deleted() will return TRUE after this function has been called on a 
mark; gtk_text_mark_get_deleted() indicates that a mark no longer belongs to a buffer. The "mark_deleted" 
signal will be emitted as notification after the mark is deleted. 


Parameters: 
buffer [in] a GtkTextBuffer 
mark [in] a GtkTextMark in buffer 


Returns: 


void 


6.44.2.14 void gtk_text_buffer_delete_mark_by_name (GtkTextBuffer x buffer, const gchar x 
name) 


Deletes the mark named name; the mark must exist. 


See gtk_text_buffer_delete_mark() for details. 


Parameters: 
buffer [in] a GtkTextBuffer 


name [in] name of a mark in buffer 


Returns: 


void 


6.44.2.15 gboolean gtk_text_buffer_delete_selection (GtkTextBuffer x buffer, gboolean interactive, 
gboolean default_editable) 


Deletes the range between the "insert" and "selection_bound" marks, that is, the currently-selected text. 
If interactive is TRUE, the editability of the selection will be considered (users can’t delete uneditable 
text). 
Parameters: 
buffer [in] a GtkTextBuffer 
interactive [in] whether the deletion is caused by user interaction 


default_editable [in] whether the buffer is editable by default 


Returns: 


whether there was a non-empty selection to delete 
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6.44.2.16 void gtk_text_buffer_end_user_action (GtkTextBuffer x buffer) 


Should be paired with a call to gtk_text_buffer_begin_user_action(). 


See that function for a full explanation. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


void 


6.44.2.17 void gtk_text_buffer_get_bounds (GtkTextBuffer x buffer, GtkTextlter x start, 
GtkTextIter « end) 
Retrieves the first and last iterators in the buffer, i.e. 


the entire buffer lies within the range [start,end). 


Parameters: 
buffer [in] a GtkTextBuffer 
start [in] iterator to initialize with first position in the buffer 


end [in] iterator to initialize with the end iterator 


Returns: 


void 


6.44.2.18 gint gtk_text_buffer_get_char_count (GtkTextBuffer x buffer) 


Gets the number of characters in the buffer; note that characters and bytes are not the same, you can’t e.g. 


expect the contents of the buffer in string form to be this many bytes long. The character count is cached, 
so this function is very fast. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


number of characters in the buffer 


6.44.2.19 GtkTargetList« gtk_text_buffer_get_copy_target_list (GtkTextBuffer x buffer) 


This function returns the list of targets this text buffer can provide for copying and as DND source. 


The targets in the list are added with info values from the GtkTextBufferTargetInfo enum, using gtk_- 
target_list_add_rich_text_targets() and gtk_target_list_add_text_targets() 
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Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


void 


6.44.2.20 void gtk_text_buffer_get_end_iter (GtkTextBuffer x buffer, GtkTextlter x iter) 


Initializes iter with the "end iterator," one past the last valid character in the text buffer. 


If dereferenced with gtk_text_iter_get_char(), the end iterator has a character value of 0. The entire buffer 
lies in the range from the first position in the buffer (call gtk_text_buffer_get_start_iter() to get character 
position 0) to the end iterator. 


Parameters: 
buffer [in] a GtkTextBuffer 


iter [in] iterator to initialize 


Returns: 


void 


6.44.2.21 gboolean gtk_text_buffer_get_has_selection (GtkTextBuffer x buffer) 


Indicates whether the buffer has some text currently selected. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


TRUE if the there is text selected 


6.44.2.22  GtkTextMarkx gtk_text_buffer_get_insert (GtkTextBuffer x buffer) 


Returns the mark that represents the cursor (insertion point). 

Equivalent to calling gtk_text_buffer_get_mark() to get the mark named "insert", but very slightly more 
efficient, and involves less typing. 

Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


insertion point mark 
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6.44.2.23 void gtk_text_buffer_get_iter_at_child_anchor (GtkTextBuffer x buffer, GtkTextlter + 
iter, GtkTextChildAnchor * anchor) 


Obtains the location of anchor within buffer. 


Parameters: 
buffer [in] a GtkTextBuffer 
iter [in] an iterator to be initialized 


anchor [in] a child anchor that appears in buffer 


Returns: 


void 


6.44.2.24 void gtk_text_buffer_get_iter_at_line (GtkTextBuffer x buffer, GtkTextlter x iter, gint 
line_number) 


Initializes iter to the start of the given line. 


Parameters: 
buffer [in] a GtkTextBuffer 
iters [in] iterator to initialize 


line_number [in] line number counting from 0 


Returns: 


void 


6.44.2.25 void gtk_text_buffer_get_iter_at_line_index (GtkTextBuffer x buffer, GtkTextlter + iter, 
gint line_number, gint byte_index) 


Obtains an iterator pointing to byte_index within the given line. 
byte_index must be the start of a UTF-8 character, and must not be beyond the end of the line. Note bytes, 
not characters; UTF-8 may encode one character as multiple bytes. 
Parameters: 
buffer [in] a GtkTextBuffer 
iter [in] iterator to initialize 
line_number [in] line number counting from 0 


byte_index [in] byte index from start of line 


Returns: 


void 
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6.44.2.26 void gtk_text_buffer_get_iter_at_line_offset (GtkTextBuffer x buffer, GtkTextlter x iter, 
gint line_number, gint char_offset) 


Obtains an iterator pointing to char_offset within the given line. 

The char_offset must exist, offsets off the end of the line are not allowed. Note characters, not bytes; UTF-8 
may encode one character as multiple bytes. 

Parameters: 


buffer [in] a GtkTextBuffer 
iter [in] iterator to initialize 
line_number [in] line number counting from 0 


char_offset [in] char offset from start of line 


Returns: 


void 


6.44.2.27 void gtk_text_buffer_get_iter_at_mark (GtkTextBuffer « buffer, GtkTextlter + iter, 
GtkTextMark x mark) 


Initializes iter with the current position of mark. 


Parameters: 


buffer [in] a GtkTextBuffer 
iter [in] iterator to initialize 
mark [in] a GtkTextMark in buffer 


Returns: 


void 


6.44.2.28 void gtk_text_buffer_get_iter_at_offset (GtkTextBuffer x buffer, GtkTextlter x iter, gint 
char_offset) 


Initializes iter to a position char_offset chars from the start of the entire buffer. 

If char_offsetis -1 or greater than the number of characters in the buffer, iter is initialized to the end iterator, 
the iterator one past the last valid character in the buffer. 

Parameters: 


buffer [in] a GtkTextBuffer 
iter [in] iterator to initialize 


char_offset [in] char offset from start of buffer, counting from 0, or -1 


Returns: 


void 
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6.44.2.29 gint gtk_text_buffer_get_line_count (GtkTextBuffer x buffer) 


Obtains the number of lines in the buffer. 


This value is cached, so the function is very fast. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


number of lines in the buffer 


6.44.2.30  GtkTextMarkx gtk_text_buffer_get_mark (GtkTextBuffer x buffer, const gchar * name) 


Returns the mark named name in buffer buffer, or NULL if no such mark exists in the buffer. 


Parameters: 


buffer [in] a GtkTextBuffer 


name [in] a mark name 


Returns: 


a GtkTextMark, or NULL 


6.44.2.31 gboolean gtk_text_buffer_get_modified (GtkTextBuffer x buffer) 


Indicates whether the buffer has been modified since the last call to gtk_text_buffer_set_modified() set the 
modification flag to FALSE. 


Used for example to enable a "save" function in a text editor. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


TRUE if the buffer has been modified 


6.44.2.32 GtkTargetList« gtk_text_buffer_get_paste_target_list (GtkTextBuffer x buffer) 


This function returns the list of targets this text buffer supports for pasting and as DND destination. 


The targets in the list are added with info values from the GtkTextBufferTargetInfo enum, using gtk_- 
target_list_add_rich_text_targets() and gtk_target_list_add_text_targets() 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


the GtkTargetList 
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6.44.2.33 GtkTextMarkx gtk_text_buffer_get_selection_bound (GtkTextBuffer x buffer) 


Returns the mark that represents the selection bound. 


Equivalent to calling gtk_text_buffer_get_mark() to get the mark named "selection_bound", but very 
slightly more efficient, and involves less typing. The currently-selected text in buffer is the region be- 
tween the "selection_bound" and "insert" marks. If "selection_bound" and "insert" are in the same place, 
then there is no current selection. gtk_text_buffer_get_selection_bounds() is another convenient function 
for handling the selection, if you just want to know whether there’s a selection and what its bounds are. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


selection bound mark 


6.44.2.34 gboolean gtk_text_buffer_get_selection_bounds (GtkTextBuffer « buffer, GtkTextIter x 
start, GtkTextIter x end) 


Returns TRUE if some text is selected; places the bounds of the selection in start and end (if the selection 
has length 0, then start and end are filled in with the same value). 


start and end will be in ascending order. If start and end are NULL, then they are not filled in, but the return 
value still indicates whether text is selected. 


Parameters: 
buffer [in] a GtkTextBuffer a GtkTextBuffer 
start [in] iterator to initialize with selection start 


end [in] iterator to initialize with selection end 


Returns: 


whether the selection has nonzero length 


6.44.2.35 gchar» gtk_text_buffer_get_slice (GtkTextBuffer x buffer, const GtkTextlter x start, 
const GtkTextIter x end, gboolean include_hidden_chars) 


Returns the text in the range [start,end). 


Excludes undisplayed text (text marked with tags that set the invisibility attribute) if include_hidden_- 
chars is FALSE. The returned string includes a OXFFFC character whenever the buffer contains embedded 
images, so byte and character indexes into the returned string do correspond to byte and character indexes 
into the buffer. Contrast with gtk_text_buffer_get_text(). Note that OxFFFC can occur in normal text as 
well, so it is not a reliable indicator that a pixbuf or widget is in the buffer. 


Parameters: 
buffer [in] a GtkTextBuffer 


start [in] start of a range 


end [in] end of a range 
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include_hidden_chars [in] whether to include invisible text 


Returns: 


an allocated UTF-8 string 


6.44.2.36 void gtk_text_buffer_get_start_iter (GtkTextBuffer x buffer, GtkTextlter x iter) 


Initialized iter with the first position in the text buffer. 


This is the same as using gtk_text_buffer_get_iter_at_offset() to get the iter at character offset 0. 


Parameters: 


buffer [in] a GtkTextBuffer 


iter [in] iterator to initialize 


Returns: 


void 


6.44.2.37 GtkTextTagTablex gtk_text_buffer_get_tag_table (GtkTextBuffer x buffer) 


Get the GtkTextTagTable associated with this buffer. 


Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


the buffer’s tag table 


6.44.2.38 gchar» gtk_text_buffer_get_text (GtkTextBuffer x buffer, const GtkTextIter x start, const 
GtkTextlter x end, gboolean include_hidden_chars) 


Returns the text in the range [start,end). 


Excludes undisplayed text (text marked with tags that set the invisibility attribute) if include_hidden_chars 
is FALSE. Does not include characters representing embedded images, so byte and character indexes into 
the returned string do not correspond to byte and character indexes into the buffer. Contrast with gtk_text_- 
buffer_get_slice(). 


Parameters: 


buffer [in] a GtkTextBuffer 
start [in] start of a range 
end [in] end of a range 


include_hidden_chars [in] whether to include invisible text 


Returns: 


an allocated UTF-8 string 
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6.44.2.39 void gtk_text_buffer_insert (GtkTextBuffer « buffer, GtkTextlter x iter, const gchar + 
text, gint len) 
Inserts len bytes of text at position iter. 


If len is -1, text must be nul-terminated and will be inserted in its entirety. Emits the "insert_text" signal; 
insertion actually occurs in the default handler for the signal. iter is invalidated when insertion occurs 
(because the buffer contents change), but the default signal handler revalidates it to point to the end of the 
inserted text. 
Parameters: 

buffer [in] a GtkTextBuffer 

iter [in] a position in the buffer 

text [in] UTF-8 format text to insert 


len [in] length of text in bytes, or -1 


Returns: 


void 


6.44.2.40 void gtk_text_buffer_insert_at_cursor (GtkTextBuffer x buffer, const gchar x text, gint 
len) 


Simply calls gtk_text_buffer_insert(), using the current cursor position as the insertion point. 


Parameters: 


buffer [in] a GtkTextBuffer 
text [in] some text in UTF-8 format 


len [in] length of text, in bytes 


Returns: 


void 


6.44.2.41 void gtk_text_buffer_insert_child_anchor (GtkTextBuffer x buffer, GtkTextIter x iter, 
GtkTextChildAnchor * anchor) 


Inserts a child widget anchor into the text buffer at iter. 


The anchor will be counted as one character in character counts, and when obtaining the buffer contents as 
a string, will be represented by the Unicode "object replacement character" OxFFFC. Note that the "slice" 
variants for obtaining portions of the buffer as a string include this character for child anchors, but the 
"text" variants do not. e.g. see gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). Consider gtk_- 
text_buffer_create_child_anchor() as a more convenient alternative to this function. The buffer will add a 
reference to the anchor, so you can unref it after insertion. 


Parameters: 


buffer [in] a GtkTextBuffer 


iter [in] location to insert the anchor 
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anchor [in] a GtkTextChildAnchor 


Returns: 


void 


6.44.2.42  gboolean gtk_text_buffer_insert_interactive (GtkTextBuffer x buffer, GtkTextlIter x iter, 
const gchar + text, gint len, gboolean default_editable) 


Like gtk_text_buffer_insert(), but the insertion will not occur if iter is at a non-editable location in the 
buffer. 


Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is 
interactive). 


default_editable indicates the editability of text that doesn’t have a tag affecting editability applied to it. 
Typically the result of gtk_text_view_get_editable() is appropriate here. 
Parameters: 

buffer [in] a GtkTextBuffer 

iter [in] a position in buffer 

text [in] some UTF-8 text 

len [in] length of text in bytes, or -1 

default_editable [in] default editability of buffer 


Returns: 


whether text was actually inserted 


6.44.2.43 gboolean gtk_text_buffer_insert_interactive_at_cursor (GtkTextBuffer * buffer, const 
gchar x text, gint len, gboolean default_editable) 


Calls gtk_text_buffer_insert_interactive() at the cursor position. 


default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. 
Typically the result of gtk_text_view_get_editable() is appropriate here. 
Parameters: 

buffer [in] a GtkTextBuffer 

text [in] UTF-8 text to insert 

len [in] length of text in bytes, or -1 

default_editable [in] default editability of buffer 


Returns: 


whether text was actually inserted 
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6.44.2.44 void gtk_text_buffer_insert_pixbuf (GtkTextBuffer x buffer, GtkTextlter x iter, 
GdkPixbuf x pixbuf) 


Inserts an image into the text buffer at iter. 


The image will be counted as one character in character counts, and when obtaining the buffer contents as 
a string, will be represented by the Unicode "object replacement character" OxFFFC. Note that the "slice" 
variants for obtaining portions of the buffer as a string include this character for pixbufs, but the "text" 
variants do not. e.g. see gtk_text_buffer_get_slice() and gtk_text_buffer_get_text(). 

Parameters: 


buffer [in] a GtkTextBuffer 
iter [in] location to insert the pixbuf 


pixbuf [in] a GdkPixbuf 


Returns: 


void 


6.44.2.45 void gtk_text_buffer_insert_range (GtkTextBuffer x buffer, GtkTextlter x iter, const 
GtkTextlIter x start, const GtkTextlter « end) 


Copies text, tags, and pixbufs between start and end (the order of start and end doesn’t matter) and inserts 
the copy at iter. 


Used instead of simply getting/inserting text because it preserves images and tags. If start and end are in a 
different buffer from buffer, the two buffers must share the same tag table. 


Implemented via emissions of the insert_text and apply_tag signals, so expect those. 


Parameters: 
buffer [in] a GtkTextBuffer 
iter [in] a position in buffer 
start [in] a position in a GtkTextBuffer 


end [in] another position in the same buffer as start 


Returns: 


void 


6.44.2.46 gboolean gtk_text_buffer_insert_range_interactive (GtkTextBuffer x buffer, GtkTextIter 
x iter, const GtkTextlter x start, const GtkTextlter « end, gboolean default_editable) 


Same as gtk_text_buffer_insert_range(), but does nothing if the insertion point isn't editable. 


The default_editable parameter indicates whether the text is editable at iter if no tags enclosing iter affect 
editability. Typically the result of gtk_text_view_get_editable() is appropriate here. 


Parameters: 


buffer [in] a GtkTextBuffer 
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iter [in] a position in buffer 
start [in] a position in a GtkTextBuffer 
end [in] another position in the same buffer as start 


default_editable [in] default editability of the buffer 


Returns: 


whether an insertion was possible at iter 


6.44.2.47 void gtk_text_buffer_insert_with_tags (GtkTextBuffer x buffer, GtkTextIter iter, const 
gchar x text, gint len, GtkTextTag x first_tag, ...) 


Inserts text into buffer at iter, applying the list of tags to the newly-inserted text. 


The last tag specified must be NULL to terminate the list. Equivalent to calling gtk_text_buffer_insert(), 
then gtk_text_buffer_apply_tag() on the inserted text; gtk_text_buffer_insert_with_tags() is just a conve- 
nience function. 


Parameters: 


buffer [in] a GtkTextBuffer 

iter [in] an iterator in buffer 

text [in] UTF-8 text 

len [in] length of text, or -1 

first_tag [in] first tag to apply to text 

. [in] NULL-terminated list of tags to apply 


Returns: 


void 


6.44.2.48 void gtk_text_buffer_insert_with_tags_by_name (GtkTextBuffer x buffer, GtkTextlter + 
iter, const gchar + text, gint len, const gchar x first_tag_name, ...) 


Same as gtk _text_buffer_insert_with_tags(), but allows you to pass in tag names instead of tag objects. 


Parameters: 


buffer [in] a GtkTextBuffer 

iter [in] an iterator in buffer 

text [in] UTF-8 text 

len [in] length of text, or -1 

first_tag [in] name of a tag to apply to text 


. [in] more tag names 


Returns: 


void 
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6.44.2.49 void gtk_text_buffer_move_mark (GtkTextBuffer * buffer, GtkTextMark x mark, const 
GtkTextIter x where) 


Moves mark to the new location where. 


Emits the "mark_set" signal as notification of the move. 


Parameters: 

buffer [in] a GtkTextBuffer 

mark [in] a GtkTextMark 

where [in] new location for mark in buffer 
Returns: 


void 


6.44.2.50 void gtk_text_buffer_move_mark_by_name (GtkTextBuffer x buffer, const gchar x 
name, const GtkTextIter x where) 


Moves the mark named name (which must exist) to location where. 


See gtk_text_buffer_move_mark() for details. 


Parameters: 
buffer [in] a GtkTextBuffer 
name [in] name of a mark 
where [in] new location for mark 
Returns: 


void 


6.44.2.51 GtkTextBuffer* gtk_text_buffer_new (GtkTextTagTable x table) 


Creates a new text buffer. 
table is NULL to create a new one 
Parameters: 


table [in] a tag table, or NULL to create a new one 


Returns: 


a new text buffer 


6.44.2.52 void gtk_text_buffer_paste_clipboard (GtkTextBuffer « buffer, GtkClipboard x 
clipboard, GtkTextlter x override_location, gboolean default_editable) 


Pastes the contents of a clipboard at the insertion point, or at override_location. 


(Note : pasting is asynchronous, that is, we’ll ask for the paste data and return, and at some point later after 
the main loop runs, the paste data will be inserted.) 
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Parameters: 
buffer [in] a GtkTextBuffer 
clipboard [in] the GtkClipboard to paste from 
override_location [in] location to insert pasted text, or NULL for at the cursor 


default_editable [in] whether the buffer is editable by default 


Returns: 


void 


6.44.2.53 void gtk_text_buffer_place_cursor (GtkTextBuffer x buffer, const GtkTextIter * where) 


This function moves the "insert" and "selection_bound" marks simultaneously. 


If you move them to the same place in two steps with gtk_text_buffer_move_mark(), you will temporarily 
select a region in between their old and new locations, which can be pretty inefficient since the temporarily- 
selected region will force stuff to be recalculated. This function moves them as a unit, which can be 
optimized. 


Parameters: 
buffer [in] a GtkTextBuffer 


where [in] where to put the cursor 


Returns: 


void 


6.44.2.54 void gtk_text_buffer_remove_all_tags (GtkTextBuffer x buffer, const GtkTextlter x start, 
const GtkTextlter x end) 


Removes all tags in the range between start and end. 
Be careful with this function; it could remove tags added in code unrelated to the code you're currently 
writing. That is, using this function is probably a bad idea if you have two or more unrelated code sections 
that add tags. 
Parameters: 

buffer [in] a GtkTextBuffer 

start [in] one bound of range to be untagged 


end [in] other bound of range to be untagged 


Returns: 


void 
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6.44.2.55 void gtk_text_buffer_remove_selection_clipboard (GtkTextBuffer + buffer, 
GtkClipboard « clipboard) 


Removes a GtkClipboard added with gtk_text_buffer_add_selection_clipboard(). 


Parameters: 
buffer [in] a GtkTextBuffer 
clipboard [in] a GtkClipboard added to buffer by gtk_text_buffer_add_selection_clipboard(). 


Returns: 


void 


6.44.2.56 void gtk_text_buffer_remove_tag (GtkTextBuffer x buffer, GtkTextTag « tag, const 
GtkTextIter x start, const GtkTextIter « end) 


Emits the "remove_tag" signal. 


The default handler for the signal removes all occurrences of tag from the given range. start and end don't 
have to be in order. 


Parameters: 
buffer [in] a GtkTextBuffer 
tag [in] a GtkTextTag 
start [in] one bound of range to be untagged 


end [in] other bound of range to be untagged 


Returns: 


void 


6.44.2.57 void gtk_text_buffer_remove_tag_by_name (GtkTextBuffer * buffer, const gchar x 
name, const GtkTextIter x start, const GtkTextlter « end) 


Calls gtk_text_tag_table_lookup() on the buffer’s tag table to get a GtkTextTag, then calls gtk_text_buffer_- 
remove_tag(). 


Parameters: 
buffer [in] a GtkTextBuffer 
name [in] name of a GtkTextTag 
start [in] one bound of range to be untagged 


end [in] other bound of range to be untagged 


Returns: 


void 
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6.44.2.58 void gtk_text_buffer_select_range (GtkTextBuffer x buffer, const GtkTextIter x ins, 
const GtkTextlter « bound) 


This function moves the "insert" and "selection_bound" marks simultaneously. 


If you move them in two steps with gtk_text_buffer_move_mark(), you will temporarily select a region in 
between their old and new locations, which can be pretty inefficient since the temporarily-selected region 
will force stuff to be recalculated. This function moves them as a unit, which can be optimized. 


Parameters: 


buffer [in] a GtkTextBuffer 
ins [in] where to put the "insert" mark 


bound [in] where to put the "selection_bound" mark 


Returns: 


void 


6.44.2.59 void gtk_text_buffer_set_modified (GtkTextBuffer « buffer, gboolean setting) 


Used to keep track of whether the buffer has been modified since the last time it was saved. 

Whenever the buffer is saved to disk, call gtk_text_buffer_set_modified (buffer, FALSE). When the buffer 
is modified, it will automatically toggled on the modified bit again. When the modified bit flips, the buffer 
emits a "modified_changed" signal. 

Parameters: 


buffer [in] a GtkTextBuffer 


setting [in] modification flag setting 


Returns: 


void 


6.44.2.60 void gtk_text_buffer_set_text (GtkTextBuffer x buffer, const gchar x text, gint len) 


Deletes current contents of buffer, and inserts text instead. 


If len is -1, text must be nul-terminated. text must be valid UTF-8. 


Parameters: 


buffer [in] a GtkTextBuffer 
text [in] UTF-8 text to insert 
len [in] length of text in bytes 


Returns: 


void 
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6.45 GtkTextTag 


6.45.1 Detailed Description 


A tag that can be applied to text in a GtkTextBuffer. 


You may wish to begin by reading the text widget conceptual overview which gives an overview of all the 
objects and data types related to the text widget and how they work together. 


Tags should be in the GtkTextTagTable for a given GtkTextBuffer before using them with that buffer. 


gtk_text_buffer_create_tag() is the best way to create tags. See gtk-demo for numerous examples. 


The "invisible" property was not implemented for GTK+ 2.0; it's planned to be implemented in future 
releases. 
Data Structures 


e struct _GtkTextTag 


GtkTextTag instance structure. 


e struct _GtkTextTagClass 


GtkTextTag instance class structure. 


e struct _GtkTextAppearance 


GtkTextAppearance instance structure. 


e struct _GtkTextAttributes 


GtkTextAttributes instance structure. 


Functions 


GtkTextTag * gtk_text_tag_new (const gchar xname) 
Creates a GtkTextTag. 


e gint gtk_text_tag_get_priority (GtkTextTag x*tag) 
Get the tag priority. 


e void gtk_text_tag_set_priority (GtkTextTag tag, gint priority) 
Sets the priority of a GtkTextTag. 


e gboolean gtk_text_tag event (GtkTextTag *tag, GObject *event_object, GdkEvent *event, const 
GtkTextlter xiter) 


Emits the "event" signal on the GtkTextTag. 


GtkTextAttributes * gtk_text_attributes_new (void) 


Creates a GtkTextAttributes, which describes a set of properties on some text. 


GtkTextAttributes * gtk_text_attributes_copy (GtkTextAttributes x*src) 


Copies src and returns a new GtkTextAttributes. 
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e void gtk_text_attributes_copy_values (GtkTextAttributes «src, GtkTextAttributes *dest) 


Copies the values from src to dest so that dest has the same values as src. 


e void gtk_text_attributes_unref (GtkTextAttributes +values) 


Decrements the reference count on values, freeing the structure if the reference count reaches 0. 


e GtkTextAttributes + gtk_text_attributes_ref (GtkTextAttributes *values) 


Increments the reference count on values. 


6.45.2 Function Documentation 
6.45.2.1 GtkTextAttributesx gtk_text_attributes_copy (GtkTextAttributes x src) 


Copies src and returns a new GtkTextAttributes. 


Parameters: 


src [in] a GtkTextAttributes to be copied 


Returns: 


a copy of src 


6.45.2.2 void gtk_text_attributes_copy_values (GtkTextAttributes « src, GtkTextAttributes x dest) 


Copies the values from src to dest so that dest has the same values as src. 


Frees existing values in dest. 


Parameters: 
src [in] a GtkTextAttributes 


dest [in] another GtkTextAttributes 


Returns: 


void 


6.45.2.3 GtkTextAttributes* gtk_text_attributes_new (void) 


Creates a GtkTextAttributes, which describes a set of properties on some text. 


Returns: 


a new GtkTextAttributes 
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6.45.2.4 GtkTextAttributesx gtk_text_attributes_ref (GtkTextAttributes * values) 
Increments the reference count on values. 


Parameters: 


values [in] a GtkTextTag 


Returns: 


the GtkTextAttributes that were passed in 


6.45.2.5 void gtk_text_attributes_unref (GtkTextAttributes * values) 
Decrements the reference count on values, freeing the structure if the reference count reaches 0. 


Parameters: 


values [in] a GtkTextAttributes 


Returns: 


void 


6.45.2.6 gboolean gtk_text_tag_event (GtkTextTag « tag, GObject x event_object, GdkEvent + 
event, const GtkTextlter + iter) 


Emits the "event" signal on the GtkTextTag. 


Parameters: 


tag [in] a GtkTextTag 
event_object [in] object that received the event, such as a widget 
event [in] the event 


iter [in] location where the event was received 


Returns: 


result of signal emission (whether the event was handled) 


6.45.2.7 gint gtk_text_tag get priority (GtkTextTag x tag) 
Get the tag priority. 


Parameters: 


tag [in] a GtkTextTag 


Returns: 


The tag's priority. 
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6.45.2.8 GtkTextTag* gtk_text_tag_new (const gchar x name) 


Creates a GtkTextTag. 


Configure the tag using object arguments, i.e. using g_object_set(). 


Parameters: 


name [in] tag name, or NULL 


Returns: 


a new GtkTextTag 


6.45.2.9 void gtk_text_tag set_priority (GtkTextTag x tag, gint priority) 


Sets the priority of a GtkTextTag. 


Valid priorities are start at O and go to one less than gtk_text_tag_table_get_size(). Each tag in a table 
has a unique priority; setting the priority of one tag shifts the priorities of all the other tags in the table 
to maintain a unique priority for each tag. Higher priority tags "win" 1f two tags both set the same text 
attribute. When adding a tag to a tag table, it will be assigned the highest priority in the table by default; so 
normally the precedence of a set of tags is the order in which they were added to the table, or created with 
gtk_text_buffer_create_tag(), which adds the tag to the buffer’s table automatically. 


Parameters: 


tag [in] a GtkTextTag 


priority [in] the new priority 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.46 GtkTextTagTable 431 


6.46 GtkTextTagTable 


6.46.1 Detailed Description 


Collection of tags that can be used together. 


You may wish to begin by reading the text widget conceptual overview which gives an overview of all the 
objects and data types related to the text widget and how they work together. 
Data Structures 


e struct _GtkTextTagTable 


GtkTextTagTable instance structure. 


e struct _GtkTextTagTableClass 


GtkTextTagTable instance class structure. 


Functions 


e GtkTextTagTable « gtk_text_tag_table_new (void) 


Creates a new GtkTextTagTable. 


void gtk_text_tag_table_add (GtkTextTagTable *table, GtkTextTag *tag) 
Add a tag to the table. 


void gtk_text_tag_table_remove (GtkTextTagTable «table, GtkTextTag +tag) 


Remove a tag from the table. 


GtkTextTag * gtk_text_tag_table_lookup (GtkTextTagTable «table, const gchar xname) 


Look up a named tag. 


void gtk_text_tag_table_foreach (GtkTextTagTable xtable, GtkTextTagTableForeach func, gpointer 
data) 


Calls func on each tag in table, with user data data. 


gint gtk_text_tag_table_get_size (GtkTextTagTable table) 


Returns the size of the table (number of tags). 


6.46.2 Function Documentation 
6.46.2.1 void gtk_text_tag_table_add (GtkTextTagTable x table, GtkTextTag x tag) 


Add a tag to the table. 


The tag is assigned the highest priority in the table. tag must not be in a tag table already, and may not have 
the same name as an already-added tag. 
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Parameters: 
table [in] a GtkTextTagTable 
tag [in] a GtkTextTag 


Returns: 


void 


6.46.2.2 void gtk_text_tag_table_foreach (GtkTextTagTable « table, GtkTextTagTableForeach 
func, gpointer data) 
Calls func on each tag in table, with user data data. 


Note that the table may not be modified while iterating over it (you can’t add/remove tags). 


Parameters: 
table [in] a GtkTextTagTable 
func [in] a function to call on each tag 


data [in] user data 


Returns: 


void 


6.46.2.3 gint gtk_text_tag_table_get_size (GtkTextTagTable x table) 


Returns the size of the table (number of tags). 


Parameters: 


table [in] a GtkTextTagTable 


Returns: 


number of tags in table 


6.46.2.4 GtkTextTagx gtk_text_tag_table_lookup (GtkTextTagTable x table, const gchar * name) 
Look up a named tag. 


Parameters: 
table [in] a GtkTextTagTable 


name [in] name of a tag 


Returns: 


The tag, or NULL if none by that name is in the table. 
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6.46.2.5 GtkTextTagTablex gtk_text_tag_table_new (void) 


Creates a new GtkTextTagTable. 


The table contains no tags by default. 


Returns: 


a new GtkTextTagTable 


6.46.2.6 void gtk_text_tag_table_remove (GtkTextTagTable x table, GtkTextTag + tag) 


Remove a tag from the table. 


This will remove the table’s reference to the tag, so be careful - the tag will end up destroyed if you don’t 
have a reference to it. 


Parameters: 


table [in] a GtkTextTagTable 
tag [in] a GtkTextTag 


Returns: 


void 
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6.47 GtkTextView 


6.47.1 Detailed Description 


Widget that displays a GtkTextBuffer, in Multiline. 
Its a widget which can display a GtkTextBuffer. Each buffer can be displayed by any number of views. 


Murr 


Figure 6.11: GtkText View 


Code Example: 


GtkWidget «view; 
GtkTextBuffer «buffer; 


view = gtk_text_view_new (); 


buffer = gtk_text_view_get_buffer (GTK_TEXT_VIEW (view) ); 


gtk_text_buffer_set_text (buffer, "Hello, this is some text", -1); 


//Now you might put the view in a container and display it on the 
//screen; when the user edits the text, signals on the buffer 
//will be emitted, such as "changed", "insert_text", and so on. 


How scrolling, validation, exposes, etc. work. 


The expose_event handler has the invariant that the onscreen lines have been validated. There are two ways 
that onscreen lines can become invalid. The first is to change which lines are onscreen. This happens when 
the value of a scroll adjustment changes. So the code path begins in gtk_text_view_value_changed() and 
goes like this: 
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e gdk_window_scroll() to reflect the new adjustment value 


e validate the lines that were moved onscreen 


e gdk_window_process_updates() to handle the exposes immediately 


The second way is that you get the "invalidated" signal from the layout, indicating that lines have become 
invalid. This code path begins in invalidated_handler() and goes like this: 


e install high-priority idle which does the rest of the steps 


e if a scroll is pending from scroll_to_mark(), do the scroll, jumping to the gtk_text_view_value_- 
changed() code path 


¢ otherwise, validate the onscreen lines 


e DO NOT process updates 


In both cases, validating the onscreen lines can trigger a scroll due to maintaining the first_para on the top 
of the screen. If validation triggers a scroll, we jump to the top of the code path for value_changed, and 
bail out of the current code path. 


Also, in size_allocate, if we invalidate some lines from changing the layout width, we need to go ahead and 
run the high-priority idle, because GTK sends exposes right after doing the size allocates without returning 
to the main loop. This is also why the high-priority idle is at a higher priority than resizing. 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkTextView 


GtkTextView instance structure. 


e struct _GtkTextViewClass 


GtkTextView instance class structure. 


Enumerations 


e enum GtkTextViewNavigationMode { GTK_TEXT_VIEW_MODE_NORMAL, GTK_TEXT_- 
VIEW_MODE_SELECTION } 


Functions 


e GtkWidget * gtk_text_view_new (void) 


Creates a new GtkTextView. 


e GtkWidget * gtk_text_view_new_with_buffer (GtkTextBuffer «buffer) 
Creates a new GtkTextView widget displaying the buffer buffer. 


e void gtk_text_view_set_buffer (GtkText View *text_view, GtkTextBuffer «buffer) 
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Sets buffer as the buffer being displayed by text_view. 


GtkTextBuffer x gtk_text_view_get_buffer (GtkTextView *text_view) 


Returns the GtkTextBuffer being displayed by this text view. 


gboolean gtk_text_view_scroll_to_iter (GtkTextView +text_view, GtkTextlter xiter, gdouble 
within_margin, gboolean use_align, gdouble xalign, gdouble yalign) 


Scrolls text_view so that iter is on the screen in the position indicated by xalign and yalign. 


void gtk_text_view_scroll_to_mark (GtkTextView x*text_view, GtkTextMark »*mark, gdouble 
within_margin, gboolean use_align, gdouble xalign, gdouble yalign) 


Scrolls text_view so that mark is on the screen in the position indicated by xalign and yalign. 


void gtk_text_view_scroll_mark_onscreen (GtkTextView *text_view, GtkTextMark +mark) 


Scrolls text_view the minimum distance such that mark is contained within the visible area of the widget. 


gboolean gtk_text_view_move_mark_onscreen (GtkTextView *text_view, GtkTextMark +mark) 


Moves a mark within the buffer so that it’s located within the currently-visible text area. 


gboolean gtk_text_view_place_cursor_onscreen (GtkTextView *text_view) 


Moves the cursor to the currently visible region of the buffer, if it isn’t there already. 


void gtk_text_view_get_visible_rect (GtkTextView *text_view, GdkRectangle *visible_rect) 


Fills visible_rect with the currently-visible region of the buffer, in buffer coordinates. 


void gtk_text_view_set_cursor_visible (GtkTextView *text_view, gboolean setting) 


Toggles whether the insertion point is displayed. 


gboolean gtk_text_view_get_cursor_visible (GtkTextView *text_view) 


Find out whether the cursor is being displayed. 


void gtk_text_view_get_iter_location (GtkTextView *text_view, const GtkTextlter xiter, GdkRect- 
angle «location) 


Gets a rectangle which roughly contains the character at iter. 


void gtk_text_view_get_iter_at_location (GtkTextView *text_view, GtkTextlter xiter, gint x, gint 
y) 


Retrieves the iterator at buffer coordinates x and y. 


void gtk_text_view_get_iter_at_position (GtkTextView *text_view, GtkTextlter xiter, gint «trailing, 
gint x, gint y) 


Retrieves the iterator pointing to the character at buffer coordinates x and y. 


void gtk_text_view_get_line_yrange (GtkTextView x*text_view, const GtkTextlter xiter, gint xy, gint 
*+height) 


Gets the y coordinate of the top of the line containing iter, and the height of the line. 


void gtk_text_view_get_line_at_y (GtkTextView »*text_view, GtkTextlter *target_iter, gint y, gint 
*line_top) 


Gets the GtkTextlter at the start of the line containing the coordinate y. 
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e void gtk text_view_buffer_to_window_coords (GtkTextView xtext_view, GtkTextWindowType 
win, gint buffer_x, gint buffer_y, gint *window_x, gint *window_y) 


Converts coordinate (buffer_x, buffer_y) to coordinates for the window win, and stores the result in 
(window_x, window_y). 


e void gtk text_view_window_to_buffer_coords (GtkTextView xtext_view, GtkTextWindowType 
win, gint window_x, gint window_y, gint «buffer_x, gint «buffer_y) 


Converts coordinates on the window identified by win to buffer coordinates, storing the result in (buffer_- 
x, buffer_y). 


e GdkWindow x gtk _text_view_get_window (GtkTextView *text_view, GtkTextWindowType win) 


Retrieves the GdkWindow corresponding to an area of the text view; possible windows include the overall 
widget window, child windows on the left, right, top, bottom, and the window that displays the text buffer. 


e GtkTextWindowType gtk text_view_get_window_type (GtkTextView *text_view, GdkWindow 
*Wwindow) 


Usually used to find out which window an event corresponds to. 


e void gtk_text_view_set_border_window_size (GtkTextView x*text_view, GtkTextWindowType type, 
gint size) 


Sets the width of GTK_TEXT_WINDOW_LEFT or GTK_TEXT_WINDOW_RIGHT, or the height of GTK_- 
TEXT_WINDOW_TOP or GTK_TEXT_WINDOW_BOTTOM. 


e gint gtk text_view_get_border_window_size (GtkTextView  xtext_view, GtkTextWindowType 
type) 
Gets the width of the specified border window. 


e gboolean gtk_text_view_forward_display_line (GtkTextView +text_view, GtkTextlter xiter) 


Moves the given iter forward by one display (wrapped) line. 


e gboolean gtk_text_view_backward_display_line (GtkTextView *text_view, GtkTextlter xiter) 
Moves the given iter backward by one display (wrapped) line. 


e gboolean gtk_text_view_forward_display_line_end (GtkTextView *text_view, GtkTextlter xiter) 


Moves the given iter forward to the next display line end. 


e gboolean gtk_text_view_backward_display_line_start (GtkTextView  «*text_view,  GtkTextlter 
xiter) 


Moves the given iter backward to the next display line start. 


e gboolean gtk_text_view_starts_display_line (GtkTextView x*text_view, const GtkTextlter xiter) 


Determines whether iter is at the start of a display line. 


e gboolean gtk_text_view_move_visually (GtkTextView *text_view, GtkTextlter xiter, gint count) 


Move the iterator a given number of characters visually, treating it as the strong cursor position. 


e void gtk_text_view_add_child_at_anchor (GtkTextView »text_view, GtkWidget «child, Gtk- 
TextChildAnchor xanchor) 


Adds a child widget in the text buffer, at the given anchor. 
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void gtk_text_view_add_child_in_window (GtkTextView x*text_view, GtkWidget *child, GtkTex- 
tWindowType which_window, gint xpos, gint ypos) 


Adds a child at fixed coordinates in one of the text widget’s windows. 


void gtk_text_view_move_child (GtkTextView x*text_view, GtkWidget «child, gint xpos, gint 
ypos) 
Updates the position of a child, as for gtk_text_view_add_child_in_window(). 


void gtk_text_view_set_wrap_mode (GtkTextView x*text_view, GtkWrapMode wrap_mode) 


Sets the line wrapping for the view. 


GtkWrapMode gtk_text_view_get_wrap_mode (GtkTextView *text_view) 


Gets the line wrapping for the view. 


void gtk_text_view_set_editable (GtkTextView x*text_view, gboolean setting) 
Sets the default editability of the GtkTextView. 


gboolean gtk_text_view_get_editable (GtkTextView *text_view) 
Returns the default editability of the GtkTextView. 


void gtk_text_view_set_overwrite (GtkTextView x*text_view, gboolean overwrite) 


Changes the GtkTextView overwrite mode. 


gboolean gtk_text_view_get_overwrite (GtkTextView *text_view) 


Returns whether the GtkTextView is in overwrite mode or not. 


void gtk_text_view_set_accepts_tab (GtkTextView *text_view, gboolean accepts_tab) 


Sets the behavior of the text widget when the Tab key is pressed. 


gboolean gtk_text_view_get_accepts_tab (GtkTextView *text_view) 


Returns whether pressing the Tab key inserts a tab characters. 


void gtk_text_view_set_pixels_above_lines (GtkTextView *text_view, gint pixels_above_lines) 


Sets the default number of blank pixels above paragraphs in text_view. 


gint gtk_text_view_get_pixels_above_lines (GtkTextView *text_view) 


Gets the default number of pixels to put above paragraphs. 


void gtk_text_view_set_pixels_below_lines (GtkTextView x*text_view, gint pixels_below_lines) 


Sets the default number of pixels of blank space to put below paragraphs in text_view. 


gint gtk_text_view_get_pixels_below_lines (GtkTextView *text_view) 


Gets the value set by gtk_text_view_set_pixels_below_lines(). 


void gtk_text_view_set_pixels_inside_wrap (GtkTextView xtext_view, gint pixels_inside_wrap) 


Sets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. 


gint gtk_text_view_get_pixels_inside_wrap (GtkTextView *text_view) 


Gets the value set by gtk_text_view_set_pixels_inside_wrap(). 
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e void gtk_text_view_set_justification (GtkTextView *text_view, GtkJustification justification) 


Sets the default justification of text in text_view. 


e GtkJustification gtk_text_view_get_justification (GtkTextView *text_view) 


Gets the default justification of paragraphs in text_view. 


e void gtk_text_view_set_left_margin (GtkTextView x*text_view, gint left_margin) 


Sets the default left margin for text in text_view. 


e gint gtk_text_view_get_left_margin (GtkTextView *text_view) 


Gets the default left margin size of paragraphs in the text_view. 


e void gtk_text_view_set_right_margin (GtkTextView xtext_view, gint right_margin) 


Sets the default right margin for text in the text view. 


e gint gtk_text_view_get_right_margin (GtkTextView *text_view) 


Gets the default right margin for text in text_view. 


e void gtk_text_view_set_indent (GtkText View *text_view, gint indent) 


Sets the default indentation for paragraphs in text_view. 


e gint gtk_text_view_get_indent (GtkTextView *text_view) 


Gets the default indentation of paragraphs in text_view. 


e void gtk_text_view_set_tabs (GtkTextView *text_view, PangoTabArray tabs) 


Sets the default tab stops for paragraphs in text_view. 


e PangoTabArray « gtk_text_view_get_tabs (GtkText View *text_view) 


Gets the default tabs for text_view. 


e GtkTextAttributes x» gtk_text_view_get_default_attributes (GtkTextView *text_view) 


Obtains a copy of the default text attributes. 


e void gtk_text_view_set_max_char_length (GtkTextView xtext_view, guint max_length) 


Sets GtkTextView maximum input characters length. 


e guint gtk_text_view_get_max_char_length (GtkTextView *text_view) 


Returns the GtkTextView maximum input chars length. 


e void gtk_text_view_set_max_byte_length (GtkTextView xtext_view, guint max_length) 


Sets GtkTextView maximum allowed input in bytes. 


e guint gtk_text_view_get_max_byte_length (GtkTextView *text_view) 


Returns the GtkTextView maximum allowed input in bytes. 


e guint gtk_text_view_get_remaining_input_char_count (GtkTextView *text_view) 


Returns the count of remaining more number of chars can be entered/added. 


e guint gtk_text_view_get_remaining_input_byte_count (GtkTextView *text_view) 


Returns the count of remaining more number of bytes can be entered/added. 
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e guint gtk_text_view_get_byte_length (GtkTextView *text_view) 


Returns the Textview string size in bytes. 


e gboolean gtk_text_view_check_for_navigation (GtkTextView x*text_view, guint keyval) 


Validates whether the Navigation UP/Down/LEFT/RIGHT is valid and can move cursor. 


e void gtk_text_view_set_visibility (GtkTextView *text_view, gboolean visible) 


Sets the "x" to use in place of the actual text when gtk_text_view_set_visibility() has been called to set text 
visibility to FALSE. 


e gboolean gtk_text_view_get_visibility (GtkText View *text_view) 


Retrieves whether the text in GtkTextView is visible. 


e void gtk_text_view_set_navigation_mode (GtkTextView *text_view, GtkText ViewNavigationMode 
mode) 


Sets the Cursor movement mode. 


e GtkTextViewNavigationMode gtk_text_view_get_navigation_mode (GtkTextView x*text_view) 


Returns the current navigation Mode. 


6.47.2 Enumeration Type Documentation 


6.47.2.1 enum GtkTextViewNavigationMode 


Enumerator: 
GTK_TEXT_VIEW_MODE_NORMAL Default Navigation mode, Navigation keys moves the cur- 
sor. 
GTK_TEXT_VIEW_MODE_SELECTION Text Selection mode, Navigation keys selects the text, 
which can Cut/Copy. 


6.47.3 Function Documentation 


6.47.3.1 void gtk_text_view_add_child_at_anchor (GtkTextView x text_view, GtkWidget x child, 
GtkTextChildAnchor x anchor) 


Adds a child widget in the text buffer, at the given anchor. 


Parameters: 


text_view [in] a GtkTextView 
count [in] a GtkScrolledWindow 
anchor [in] a GtkScrolledWindow 


Returns: 


void 
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6.47.3.2 void gtk_text_view_add_child_in_window (GtkTextView « text_view, GtkWidget + child, 
GtkTextWindowType which_window, gint xpos, gint ypos) 


Adds a child at fixed coordinates in one of the text widget’s windows. 


The window must have nonzero size (see gtk_text_view_set_border_window_size()). Note that the child 
coordinates are given relative to the Gdk Window in question, and that these coordinates have no sane rela- 
tionship to scrolling. When placing a child in GTK_TEXT_WINDOW_WIDGET, scrolling is irrelevant, 
the child floats above all scrollable areas. But when placing a child in one of the scrollable windows (border 
windows or text window), you’ ll need to compute the child’s correct position in buffer coordinates any time 
scrolling occurs or buffer changes occur, and then call gtk_text_view_move_child() to update the child’s 
position. Unfortunately there’s no good way to detect that scrolling has occurred, using the current API; a 
possible hack would be to update all child positions when the scroll adjustments change or the text buffer 
changes. See bug 64518 on bugzilla.gnome.org for status of fixing this issue. 


Parameters: 
text_view [in] a GtkTextView 
child [in] a GtkWidget 
which_window [in] which window the child should appear in 
xpos [in] X position of child in window coordinates 


ypos [in] Y position of child in window coordinates 


Returns: 


void 


6.47.3.3  gboolean gtk_text_view_backward_display_line (GtkTextView « text_view, GtkTextlter « 
iter) 
Moves the given iter backward by one display (wrapped) line. 


A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph 
separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, 
display lines and paragraphs will be the same. Display lines are divided differently for each view, since 
they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents 
of the GtkTextBuffer. 


Parameters: 
text_view [in] a GtkTextView 


iter [in] a GtkTextlter 


Returns: 


TRUE if iter was moved and is not on the end iterator 


6.47.3.4 gboolean gtk_text_view_backward_display_line_start (GtkTextView + text_view, 
GtkTextlIter x iter) 


Moves the given iter backward to the next display line start. 
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A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph 
separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, 
display lines and paragraphs will be the same. Display lines are divided differently for each view, since 
they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents 
of the GtkTextBuffer. 

Parameters: 


text_view [in] a GtkTextView 
iter [in] a GtkTextlter 


Returns: 


TRUE if iter was moved and is not on the end iterator 


6.47.3.5 void gtk_text_view_buffer_to_window_coords (GtkTextView x text_view, 
GtkTextWindowType win, gint buffer_x, gint buffer_y, gint x window_x, gint x window_y) 


Converts coordinate (buffer_x, buffer_y) to coordinates for the window win, and stores the result in 
(window_x, window_y). 


Note that you can’t convert coordinates for a nonexisting window (see gtk_text_view_set_border_- 
window_size()). 


Parameters: 
text_view [in] a GtkTextView 
win [in] a GtkTextWindowType except GTK_TEXT_WINDOW_PRIVATE 
buffer_x [in] buffer x coordinate 
buffer_y [in] buffer y coordinate 
window_x [out] window x coordinate return location 


window_y [out] window y coordinate return location 


Returns: 


void 


6.47.3.6 gboolean gtk_text_view_check_for_navigation (GtkTextView « text_view, guint keyval) 
Validates whether the Navigation UP/Down/LEFT/RIGHT is valid and can move cursor. 


Parameters: 


text_view [in] a GtkTextView 


keyval [in] Key Value. GDK navigation Key Values. 


Returns: 


TRUE if the navigation key can be entered and that will move the cursor. 


Since 


LIMO R1 
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6.47.3.7 gboolean gtk_text_view_forward_display_line (GtkTextView x text_view, GtkTextlter + 
iter) 
Moves the given iter forward by one display (wrapped) line. 


A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph 
separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, 
display lines and paragraphs will be the same. Display lines are divided differently for each view, since 
they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents 
of the GtkTextBuffer. 


Parameters: 


text_view [in] a GtkTextView 
iter [in] a GtkTextlter 


Returns: 


TRUE if iter was moved and is not on the end iterator 


6.47.3.8 gboolean gtk_text_view_forward_display_line_end (GtkTextView + text_view, 
GtkTextIter x iter) 
Moves the given iter forward to the next display line end. 


A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph 
separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, 
display lines and paragraphs will be the same. Display lines are divided differently for each view, since 
they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents 
of the GtkTextBuffer. 


Parameters: 


text_view [in] a GtkTextView 
iter [in] a GtkTextlter 


Returns: 


TRUE if iter was moved and is not on the end iterator 


6.47.3.9 gboolean gtk_text_view_get_accepts_tab (GtkTextView + text_view) 


Returns whether pressing the Tab key inserts a tab characters. 


gtk_text_view_set_accepts_tab(). 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


TRUE if pressing the Tab key should insert a tab character, FALSE, if pressing the Tab key should 
move the keyboard focus. 
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6.47.3.10 gint gtk_text_view_get_border_window_size (GtkTextView x text_view, 
GtkTextWindowType type) 


Gets the width of the specified border window. 


See gtk_text_view_set_border_window_size(). 


Parameters: 

text_view [in] a GtkTextView 

type [in] window to return size from 
Returns: 


Returns [in] width of window 


6.47.3.11 GtkTextBufferx* gtk_text_view_get_buffer (GtkTextView + text_view) 


Returns the GtkTextBuffer being displayed by this text view. 


The reference count on the buffer is not incremented; the caller of this function won't own a new refer- 
ence. 


Parameters: 
text_view [in] a GtkTextView 
Returns: 


Returns [in] a GtkTextBuffer 


6.47.3.12 guint gtk_text_view_get_byte_length (GtkTextView x text_view) 


Returns the Textview string size in bytes. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


Text View size in bytes. 


Since 


LIMO R1 


6.47.3.13 gboolean gtk_text_view_get_cursor_visible (GtkTextView * text_view) 


Find out whether the cursor is being displayed. 


Parameters: 
text_view [in] a GtkTextView 
Returns: 


whether the insertion mark is visible 
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6.47.3.14 GtkTextAttributes* gtk_text_view_get_default_attributes (GtkTextView * text_view) 


Obtains a copy of the default text attributes. 


These are the attributes used for text unless a tag overrides them. You’d typically pass the default attributes 
in to gtk_text_iter_get_attributes() in order to get the attributes in effect at a given text position. 


The return value is a copy owned by the caller of this function, and should be freed. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


a new GtkTextAttributes 


6.47.3.15  gboolean gtk_text_view_get_editable (GtkTextView * text_view) 
Returns the default editability of the GtkTextView. 
Tags in the buffer may override this setting for some ranges of text. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


whether text is editable by defaults 


6.47.3.16 gint gtk_text_view_get_indent (GtkTextView x text_view) 
Gets the default indentation of paragraphs in text_view. 
Tags in the view’s buffer may override the default. The indentation may be negative. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


number of pixels of indentation 


6.47.3.17 void gtk_text_view_get_iter_at_location (GtkTextView + text_view, GtkTextlter x iter, 
gint x, gint y) 


Retrieves the iterator at buffer coordinates x and y. 


Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have 
coordinates from an event, you have to convert those to buffer coordinates with gtk_text_view_window_- 
to_buffer_coords(). 


Parameters: 


text_view [in] a GtkTextView 
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iter [in] a GtkTextlter 
x [in] x position, in buffer coordinates 


y [in] y position, in buffer coordinates 


Returns: 


void 


6.47.3.18 void gtk_text_view_get_iter_at_position (GtkTextView + text_view, GtkTextlter x iter, 
gint x trailing, gint x, gint y) 


Retrieves the iterator pointing to the character at buffer coordinates x and y. 


Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have 
coordinates from an event, you have to convert those to buffer coordinates with gtk_text_view_window_- 
to_buffer_coords(). 


Note that this is different from gtk_text_view_get_iter_at_location(), which returns cursor locations, i.e. 
positions between characters. 


Parameters: 


text_view [in] a GtkTextView 
iter [in] a GtkTextlter 


trailing [in] location to store an integer indicating where in the grapheme the user clicked. It will 
either be zero, or the number of characters in the grapheme. 0 represents the trailing edge of the 
grapheme. 


x [in] x position, in buffer coordinates 


y [in] y position, in buffer coordinates 


Returns: 


void 


6.47.3.19 void gtk_text_view_get_iter_location (GtkTextView + text_view, const GtkTextlter x iter, 
GdkRectangle * location) 


Gets a rectangle which roughly contains the character at iter. 


The rectangle position is in buffer coordinates; use gtk_text_view_buffer_to_window_coords() to convert 
these coordinates to coordinates for one of the windows in the text view. 


Parameters: 


text_view [in] a GtkTextView 
iter [in] a GtkTextlter 


location [in] bounds of the character at iter 


Returns: 


void 
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6.47.3.20 GtkJustification gtk_text_view_get_justification (GtkTextView + text_view) 


Gets the default justification of paragraphs in text_view. 


Tags in the buffer may override the default. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


default justification 


6.47.3.21 gint gtk_text_view_get left margin (GtkTextView + text_view) 


Gets the default left margin size of paragraphs in the text_view. 


Tags in the buffer may override the default. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


left margin in pixels 


6.47.3.22 void gtk_text_view_get_line_at_y (GtkTextView * text_view, GtkTextlter « target_iter, 
gint y, gint « line_top) 


Gets the GtkTextlter at the start of the line containing the coordinate y. 


y is in buffer coordinates, convert from window coordinates with gtk_text_view_window_to_buffer_- 
coords(). If non-NULL, line_top will be filled with the coordinate of the top edge of the line. 


Parameters: 


text_view [in] a GtkTextView 
target_iter [in] a GtkTextlter 
y [in] a y coordinate 


line_top [out] return location for top coordinate of the line 


Returns: 


void 


6.47.3.23 void gtk_text_view_get_line_yrange (GtkTextView x text_view, const GtkTextlter + iter, 
gint « y, gint « height) 


Gets the y coordinate of the top of the line containing iter, and the height of the line. 


The coordinate is a buffer coordinate; convert to window coordinates with gtk_text_view_buffer_to_- 
window_coords(). 
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Parameters: 


text_view [in] a GtkTextView 
iter [in] a GtkTextlter 
y [out] return location for a y coordinate 


height [out] return location for a height 


Returns: 


void 


6.47.3.24 guint gtk_text_view_get_max_byte_length (GtkTextView « text_view) 


Returns the GtkText View maximum allowed input in bytes. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


max input length in bytes 


Since 


LIMO RI 


6.47.3.25 guint gtk_text_view_get_max_char_length (GtkTextView x text_view) 


Returns the GtkTextView maximum input chars length. 


Character length is calculated based on UTF-8 encoding. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


max input length in chars 


Since 


LIMO RI 


6.47.3.26 GtkTextViewNavigationMode gtk_text_view_get_navigation_mode (GtkTextView « 
text_view) 


Returns the current navigation Mode. 


Parameters: 


text_view [in] a GtkTextView 
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Returns: 


GtkTextViewNavigationMode 


Since 


LIMO R1 


6.47.3.27 gboolean gtk_text_view_get_overwrite (GtkTextView * text_view) 


Returns whether the GtkTextView is in overwrite mode or not. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


whether text_view is in overwrite mode or not. 


6.47.3.28 gint gtk_text_view_get_pixels_above_lines (GtkTextView * text_view) 


Gets the default number of pixels to put above paragraphs. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


default number of pixels above paragraphs 


6.47.3.29 gint gtk_text_view_get_pixels_below_lines (GtkTextView x text_view) 


Gets the value set by gtk_text_view_set_pixels_below_lines(). 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


default number of blank pixels below paragraphs 


6.47.3.30 gint gtk_text_view_get_pixels_inside_wrap (GtkTextView x text_view) 


Gets the value set by gtk_text_view_set_pixels_inside_wrap(. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


default number of pixels of blank space between wrapped lines 
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6.47.3.31 guint gtk_text_view_get_remaining_input_byte_count (GtkTextView x text_view) 


Returns the count of remaining more number of bytes can be entered/added. 


Chars are based on UTF-8 encoding. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


remaining number of bytes allowed to add. 


Since 


LIMO R1 


6.47.3.32 guint gtk_text_view_get_remaining_input_char_count (GtkTextView x text_view) 


Returns the count of remaining more number of chars can be entered/added. 


Chars are based on UTF-8 encoding. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


remaining number of characters can be entered. 


Since 


LIMO RI 


6.47.3.33 gint gtk_text_view_get_right_margin (GtkTextView x text_view) 


Gets the default right margin for text in text_view. 


Tags in the buffer may override the default. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


right margin in pixels 


6.47.3.34 PangoTabArrayx gtk_text_view_get_tabs (GtkTextView x text_view) 


Gets the default tabs for text_view. 


Tags in the buffer may override the defaults. The returned array will be NULL if "standard" (8-space) tabs 
are used. Free the return value with pango_tab_array_free(). 
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Parameters: 


text_view [in] a GtkTextView 


Returns: 


copy of default tab array, or NULL if "standard" tabs are used; must be freed with pango_tab_array_- 
free(). 


6.47.3.35 gboolean gtk_text_view_get_visibility (GtkTextView + text_view) 
Retrieves whether the text in GtkText View is visible. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


FALSE if the actual text is displayed as "x". TRUE, if actual text is dislayed. 


See also: 


gtk_text_view_set_visibility 


Since 


LIMO RI 


6.47.3.36 void gtk_text_view_get_visible_rect (GtkTextView x text_view, GdkRectangle + 
visible_rect) 


Fills visible_rect with the currently-visible region of the buffer, in buffer coordinates. 


Convert to window coordinates with gtk_text_view_buffer_to_window_coords(). 


Parameters: 


text_view [in] a GtkTextView 


visible_rect [in] rectangle to fill 


Returns: 


void 


6.47.3.37 GdkWindow~« gtk_text_view_get_window (GtkTextView + text_view, 
GtkTextWindowType win) 


Retrieves the Gdk Window corresponding to an area of the text view; possible windows include the overall 
widget window, child windows on the left, right, top, bottom, and the window that displays the text buffer. 


Windows are NULL and nonexistent if their width or height is 0, and are nonexistent before the widget has 
been realized. 
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Parameters: 
text_view [in] a GtkTextView 
win [in] a GdkWindow, or NULL 
Returns: 


void 


6.47.3.38 GtkTextWindowType gtk_text_view_get_window_type (GtkTextView x text_view, 
Gdk Window x window) 


Usually used to find out which window an event corresponds to. 


If you connect to an event signal on text_view, this function should be called on event->window to see 
which window it was. 


Parameters: 


text_view [in] a GtkTextView 


window [in] a window type 


Returns: 


Returns [in] the window type. 


6.47.3.39 GtkWrapMode gtk_text_view_get_wrap_mode (GtkTextView x text_view) 


Gets the line wrapping for the view. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


the line wrap setting 


6.47.3.40 void gtk_text_view_move_child (GtkTextView + text_view, GtkWidget x child, gint xpos, 
gint ypos) 


Updates the position of a child, as for gtk_text_view_add_child_in_window(). 


Parameters: 


text_view a GtkTextView 
child [in] child widget already added to the text view 
xpos [in] new X position in window coordinates 


ypos [in] new Y position in window coordinates 


Returns: 


void 
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6.47.3.41 gboolean gtk_text_view_move_mark_onscreen (GtkTextView x text_view, GtkTextMark 
x mark) 


Moves a mark within the buffer so that it’s located within the currently-visible text area. 


Parameters: 

text_view [in] a GtkTextView 

mark [in] a mark in the buffer for text_view 
Returns: 


void 


6.47.3.42 gboolean gtk_text_view_move_visually (GtkTextView « text_view, GtkTextlter « iter, 
gint count) 


Move the iterator a given number of characters visually, treating it as the strong cursor position. 


If count is positive, then the new strong cursor position will be count positions to the right of the old cursor 
position. If count is negative then the new strong cursor position will be count positions to the left of the 
old cursor position. 


In the presence of bidirection text, the correspondence between logical and visual order will depend on the 
direction of the current run, and there may be jumps when the cursor is moved off of the end of a run. 


Parameters: 


text_view [in] a GtkTextView 
iter [in] a GtkTextlter 


count [in] number of characters to move (negative moves left, positive moves right) 


Returns: 


TRUE if iter moved and is not on the end iterator 


6.47.3.43 GtkWidget» gtk_text_view_new (void) 


Creates a new GtkTextView. 


If you don’t call gtk_text_view_set_buffer() before using the text view, an empty default buffer will be 
created for you. Get the buffer with gtk_text_view_get_buffer(). If you want to specify your own buffer, 
consider gtk_text_view_new_with_buffer(). 


Returns: 


anew GtkTextView 


6.47.3.44 GtkWidget gtk_text_view_new_with_buffer (GtkTextBuffer x buffer) 


Creates a new GtkTextView widget displaying the buffer buffer. 


One buffer can be shared among many widgets. buffer may be NULL to create a default buffer, in which 
case this function is equivalent to gtk_text_view_new(). The text view adds its own reference count to the 
buffer; it does not take over an existing reference. 
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Parameters: 


buffer [in] a GtkTextBuffer 


Returns: 


a new GtkTextView. 


6.47.3.45  gboolean gtk_text_view_place_cursor_onscreen (GtkTextView x text_view) 


Moves the cursor to the currently visible region of the buffer, if it isn’t there already. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


TRUE if the cursor had to be moved. 


6.47.3.46 void gtk_text_view_scroll_mark_onscreen (GtkTextView x text_view, GtkTextMark x 
mark) 


Scrolls text_view the minimum distance such that mark is contained within the visible area of the widget. 


Parameters: 


text_view [in] a GtkTextView 


Returns: 


void 


6.47.3.47 gboolean gtk_text_view_scroll_to_iter (GtkTextView + text_view, GtkTextlter « iter, 
gdouble within_margin, gboolean use_align, gdouble xalign, gdouble yalign) 


Scrolls text_view so that iter is on the screen in the position indicated by xalign and yalign. 


An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If use_align is 
FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The 
effective screen for purposes of this function is reduced by a margin of size within_margin. 


NOTE: This function uses the currently-computed height of the lines in the text buffer. Note that line 
heights are computed in an idle handler; so this function may not have the desired effect if it’s called before 
the height computations. To avoid oddness, consider using gtk_text_view_scroll_to_mark() which saves a 
point to be scrolled to after line validation. 


Parameters: 
text_view [in] a GtkTextView 
iter [in] a GtkTextlter 
within_margin [in] margin as a [0.0,0.5) fraction of screen size 


use_align [in] whether to use alignment arguments (if FALSE, just get the mark onscreen) 
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xalign [in] horizontal alignment of mark within visible area. 


yalign [in] vertical alignment of mark within visible area 


Returns: 


TRUE if scrolling occurred 


6.47.3.48 void gtk_text_view_scroll_to_mark (GtkTextView > text_view, GtkTextMark * mark, 
gdouble within_margin, gboolean use_align, gdouble xalign, gdouble yalign) 


Scrolls text_view so that mark is on the screen in the position indicated by xalign and yalign. 


An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If use_align is 
FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The 
effective screen for purposes of this function is reduced by a margin of size within_margin. 


Parameters: 
text_view [in] a GtkTextView 
mark [in] a GtkTextMark 
within_margin [in] margin as a [0.0,0.5) fraction of screen size 
use_align [in] whether to use alignment arguments (if FALSE, just get the mark onscreen) 
xalign [in] horizontal alignment of mark within visible area. 


yalign [in] vertical alignment of mark within visible area 


Returns: 


void 


6.47.3.49 void gtk_text_view_set_accepts_tab (GtkTextView x text_view, gboolean accepts_tab) 


Sets the behavior of the text widget when the Tab key is pressed. 


If accepts_tab is TRUE a tab character is inserted. If accepts_tab is FALSE the keyboard focus is moved to 
the next widget in the focus chain. 


Parameters: 
text_view [in] a GtkTextView 
accepts_tab [in] a GtkScrolledWindow 
Returns: 


void 


6.47.3.50 void gtk_text_view_set_border_window_size (GtkTextView « text_view, 
GtkTextWindowType type, gint size) 


Sets the width of GTK_TEXT_WINDOW_LEFT or GTK_TEXT_WINDOW_RIGHT, or the height of 
GTK_TEXT_WINDOW_TOP or GTK_TEXT_WINDOW_BOTTOM. 


Automatically destroys the corresponding window if the size is set to 0, and creates the window if the size 
is set to non-zero. This function can only be used for the "border windows," it doesn’t work with GTK_- 
TEXT_WINDOW_WIDGET, GTK_TEXT_WINDOW_TEXT, or GTK_TEXT_WINDOW_PRIVATE. 
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Parameters: 

text_view [in] a GtkTextView 

type [in] window to affect 

size [in] width or height of the window 
Returns: 


void 


6.47.3.51 void gtk_text_view_set_buffer (GtkTextView + text_view, GtkTextBuffer x buffer) 


Sets buffer as the buffer being displayed by text_view. 


The previous buffer displayed by the text view is unreferenced, and a reference is added to buffer. If you 
owned a reference to buffer before passing it to this function, you must remove that reference yourself; 
GtkTextView will not "adopt" it. 


Parameters: 


text_view [in] a GtkTextView 
buffer [in] a GtkTextBuffer 


Returns: 


void 


6.47.3.52 void gtk_text_view_set_cursor_visible (GtkTextView + text_view, gboolean setting) 


Toggles whether the insertion point is displayed. 


A buffer with no editable text probably shouldn’t have a visible cursor, so you may want to turn the cursor 
off. 


Parameters: 


text_view [in] a GtkTextView 
setting [in] whether to show the insertion cursor 


Returns: 


void 


6.47.3.53 void gtk_text_view_set_editable (GtkTextView + text_view, gboolean setting) 


Sets the default editability of the GtkTextView. 
You can override this default setting with tags in the buffer, using the "editable" attribute of tags. 
Parameters: 
text_view [in] a GtkTextView 
setting [in] whether it’s editable 
Returns: 


void 
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6.47.3.54 void gtk_text_view_set_indent (GtkTextView x text_view, gint indent) 


Sets the default indentation for paragraphs in text_view. 


Tags in the buffer may override the default. 


Parameters: 


text_view [in] a GtkTextView 


indent [in] indentation in pixels 


Returns: 


void 


6.47.3.55 void gtk_text_view_set_justification (GtkTextView « text_view, GtkJustification 
justification) 


Sets the default justification of text in text_view. 


Tags in the view’s buffer may override the default. 


Parameters: 


text_view [in] a GtkTextView 


justification [in] justification 


Returns: 


void 


6.47.3.56 void gtk_text_view_set_left_margin (GtkTextView x text_view, gint left_margin) 


Sets the default left margin for text in text_view. 


Tags in the buffer may override the default. 


Parameters: 


text_view [in] a GtkTextView 


left_margin [in] left margin in pixels 


Returns: 


void 


6.47.3.57 void gtk_text_view_set_max_byte_length (GtkTextView x text_view, guint max_length) 
Sets GtkText View maximum allowed input in bytes. 


Parameters: 


text_view [in] a GtkTextView 
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max_length [in] max input length in bytes 


Since 


LIMO R1 


6.47.3.58 void gtk_text_view_set_max_char_length (GtkTextView x text_view, guint max_length) 


Sets GtkText View maximum input characters length. 
Character length should be based on UTF-8 encoding. 
Parameters: 

text_view [in] a GtkTextView 

max [in] input length in chars 
Since 


LIMO R1 


6.47.3.59 void gtk_text_view_set_navigation_mode (GtkTextView * text_view, 
GtkText ViewNavigationMode mode) 


Sets the Cursor movement mode. 


In GTK_TEXT_VIEW_MODE NORMAL mode, navigation key event moves the cursor normally. In 
Mode GTK_TEXT_VIEW_MODE _ SELECTION, navigation key events does Text Selection from the 
current position. If it is already in text selection mode, then selection will be extended based on the 
Navigation key untill mode is reset to GTK_TEXT_VIEW_MODE_NORMAL. Default mode is GTK_- 
TEXT_VIEW_MODE_NORMAL. 


Parameters: 

text_view [in] a GtkTextView 

mode [in] GtkTextViewNavigationMode 
Returns: 

void 
Since 


LIMO RI 


6.47.3.60 void gtk_text_view_set_overwrite (GtkTextView x text_view, gboolean overwrite) 


Changes the GtkText View overwrite mode. 


Parameters: 


text_view [in] a GtkTextView 
overwrite [in] TRUE to turn on overwrite mode, FALSE to turn it off 


Returns: 


void 
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6.47.3.61 void gtk_text_view_set_pixels_above_lines (GtkTextView x text_view, gint 
pixels_above_lines) 


Sets the default number of blank pixels above paragraphs in text_view. 


Tags in the buffer for text_view may override the defaults. 


Parameters: 


text_view [in] a GtkTextView 


pixels_above_lines [in] pixels above paragraphs 


Returns: 


void 


6.47.3.62 void gtk_text_view_set_pixels_below_lines (GtkTextView x text_view, gint 
pixels_below_lines) 


Sets the default number of pixels of blank space to put below paragraphs in text_view. 


May be overridden by tags applied to text_view’s buffer. 


Parameters: 


text_view [in] a GtkTextView 


pixels_below_lines [in] pixels below paragraphs 


Returns: 


void 


6.47.3.63 void gtk_text_view_set_pixels_inside_wrap (GtkTextView x text_view, gint 
pixels_inside_wrap) 


Sets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. 


May be overridden by tags in text_view’s buffer. 


Parameters: 


text_view [in] a GtkTextView 


pixels_inside_wrap [in] default number of pixels between wrapped lines 


Returns: 


void 


6.47.3.64 void gtk_text_view_set_right_margin (GtkTextView + text_view, gint right_margin) 


Sets the default right margin for text in the text view. 


Tags in the buffer may override the default. 
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Parameters: 


text_view [in] a GtkTextView 


right_margin [in] right margin in pixels 


Returns: 


void 


6.47.3.65 void gtk_text_view_set_tabs (GtkTextView x text_view, PangoTabArray + tabs) 


Sets the default tab stops for paragraphs in text_view. 


Tags in the buffer may override the default. 


Parameters: 


text_view [in] a GtkTextView 


tabs [in] tabs as a PangoTabArray 


Returns: 


void 


6.47.3.66 void gtk_text_view_set_visibility (GtkTextView x text_view, gboolean visible) 

Sets the "x" to use in place of the actual text when gtk_text_view_set_visibility() has been called to set text 
visibility to FALSE. 

i.e. this is the character used in "password mode" to show the user how many characters have been 
typed. 

Parameters: 


text_view [in] a GtkTextView 


visible [in] FALSE to display "x" in place of actual Text. 


Returns: 


void 


See also: 


gtk_text_view_get_visibility 


Since 


LIMO R1 


6.47.3.67 void gtk_text_view_set_wrap_mode (GtkTextView x text_view, GtkWrapMode 
wrap_mode) 


Sets the line wrapping for the view. 
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Parameters: 


text_view [in] a GtkTextView 


wrap_mode [in] a GtkWrapMode 


Returns: 


void 


6.47.3.68 gboolean gtk_text_view_starts_display_line (GtkTextView x text_view, const GtkTextlter 
x iter) 


Determines whether iter is at the start of a display line. 


See gtk_text_view_forward_display_line() for an explanation of display lines vs. paragraphs. 


Parameters: 


text_view [in] a GtkTextView 


iter [in] a GtkTextlter 


Returns: 


TRUE if iter begins a wrapped line 


6.47.3.69 void gtk_text_view_window_to_buffer_coords (GtkTextView + text_view, 
GtkTextWindowType win, gint window_x, gint window_y, gint x buffer_x, gint x buffer_y) 


Converts coordinates on the window identified by win to buffer coordinates, storing the result in (buffer_- 
x,buffer_y). 


Note that you can’t convert coordinates for a nonexisting window (see gtk_text_view_set_border_- 
window_size()). 


Parameters: 
text_view [in] a GtkTextView 
win [in] a GtkTextWindowType except GTK_TEXT_WINDOW_PRIVATE 
window_x [in] window x coordinate 
window_y [in] window y coordinate 
buffer_x [out] buffer x coordinate return location 


buffer_y [out] buffer y coordinate return location 


Returns: 


void 
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6.48 Tree, List and Icon Grid Widgets 


Modules 


GtkTreeModel 


The GtkTreeModel interface defines a generic tree interface for use by the GtkTreeView widget. 


GtkTreeSelection 


The GtkTreeSelection object is a helper object to manage the selection for a GtkTreeView widget. 


GtkTreeViewColumn 


The GtkTree ViewColumn object represents a visible column in a GtkTreeView widget. 


GtkTreeview 


Widget that displays any object that implements the GtkTreeModel interface. 


GtkCell View 
A GtkCellView displays a single row of a GtkTreeModel, using cell renderers just like GtkTree View. 


GtkIconView 


GtkIconView provides an alternative view on a list model, displays the model as a grid of icons with labels. 


GtkTreeSortable 


GtkTreeSortable is an interface to be implemented by tree models which support sorting. 


GtkTreeModelSort 


The GtkTreeModelSort is a model which implements the GtkTreeSortable interface. 


GtkTreeModelFilter 


A GtkTreeModelFilter is a tree model which wraps another tree model, and can do the following things. 


GtkCellLayout 


GtkCellLayout is an interface to be implemented by all objects which want to provide a 
GtkTreeViewColumn-like API for packing cells, setting attributes and data funcs. 


GtkCellRenderer 


The GtkCellRenderer is a base class of a set of objects used for rendering a cell to a GdkDrawable. 


GtkCellEditable 


The GtkCellEditable interface must be implemented for widgets to be usable when editing the contents of a 
GtkTree View cell. 


GtkCellRendererPixbuf 


A GtkCellRendererPixbuf can be used to render an image in a cell. 


GtkCellRendererProgress 


GtkCellRendererProgress renders a numeric value as a progress par in a cell. 


GtkCellRendererText 
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A GtkCellRendererText renders a given text in its cell, using the font, color and style information provided 
by its properties. 


e GtkCellRendererToggle 
GtkCellRendererToggle renders a toggle button in a cell. 


e GtkListStore 
The GtkListStore object is a list model for use with a GtkTreeView widget. 


e GtkTreeStore 
The GtkTreeStore object is a list model for use with a GtkTree View widget. 
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6.49 GtkTreeModel 


6.49.1 Detailed Description 


The GtkTreeModel interface defines a generic tree interface for use by the GtkTree View widget. 


It is an abstract interface, and is designed to be usable with any appropriate data structure. The programmer 
just has to implement this interface on their own data type for 1t to be viewable by a GtkTreeView widget. 


The model is represented as a hierarchical tree of strongly-typed, columned data. In other words, the 
model can be seen as a tree where every node has different values depending on which column is being 
queried. The type of data found in a column is determined by using the GType system (ie. G_TYPE_INT, 
GTK_TYPE_BUTTON, G_TYPE_POINTER, etc.). 


The types are homogeneous per column across all nodes. It is important to note that this interface only 
provides a way of examining a model and observing changes. The implementation of each individual 
model decides how and if changes are made. 


In order to make life simpler for programmers who do not need to write their own specialized model, 
two generic models are provided, the GtkTreeStore and the GtkListStore. To use these, the developer 
simply pushes data into these models as necessary. These models provide the data structure as well as all 
appropriate tree interfaces. As a result, implementing drag and drop, sorting, and storing data is trivial. For 
the vast majority of trees and lists, these two models are sufficient. 


Models are accessed on a node/column level of granularity. One can query for the value of a model at a 
certain node and a certain column on that node. There are two structures used to reference a particular node 
in a model. They are the GtkTreePath and the GtkTreelter Most of the interface consists of operations on a 
GtkTreelter. 


A path is essentially a potential node. It is a location on a model that may or may not actually correspond 
to a node on a specific model. The GtkTreePath struct can be converted into either an array of unsigned 
integers or a string. The string form is a list of numbers separated by a colon. Each number refers to the 
offset at that level. Thus, the path "0" refers to the root node and the path "2:4" refers to the fifth child of 
the third node. 


By contrast, a GtkTreelter is a reference to a specific node on a specific model. It is a generic struct with 
an integer and three generic pointers. These are filled in by the model in a model-specific way. One can 
convert a path to an iterator by calling gtk_tree_model_get_iter(). These iterators are the primary way of 
accessing a model and are similar to the iterators used by GtkTextBuffer. They are generally statically 
allocated on the stack and only used for a short time. The model interface defines a set of operations using 
them for navigating the model. 


It is expected that models fill in the iterator with private data. For example, the GtkListStore model, which 
is internally a simple linked list, stores a list node in one of the pointers. The GtkTreeModelSort stores an 
array and an offset in two of the pointers. Additionally, there is an integer field. This field is generally filled 
with a unique stamp per model. This stamp is for catching errors resulting from using invalid iterators with 
a model. 


The lifecycle of an iterator can be a little confusing at first. Iterators are expected to always be valid 
for as long as the model is unchanged (and doesn't emit a signal). The model is considered to own all 
outstanding iterators and nothing needs to be done to free them from the user’s point of view. Additionally, 
some models guarantee that an iterator is valid for as long as the node it refers to is valid (most notably the 
GtkTreeStore and GtkListStore). Although generally uninteresting, as one always has to allow for the case 
where iterators do not persist beyond a signal, some very important performance enhancements were made 
in the sort model. As a result, the GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this 
behavior. 


To help show some common operation of a model, some examples are provided. The first example shows 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.49 GtkTreeModel 


465 


three ways of getting the iter at the location "3:2:5". While the first method shown is easier, the second is 


much more common, as you often get paths from callbacks. 


Code Example 


// Three ways of getting the iter pointing to the location 


{ 

GtkTreePath xpath; 
GtkTreeIter iter; 
GtkTreeIter parent_iter; 


// get the iterator from a string 
gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5" 


// get the iterator from a path 

path = gtk_tree_path_new_from_string ("3:2:5"); 
gtk_tree_model_get_iter (model, €iter, path); 
gtk_tree_path_free (path); 


walk the tree to find the iterator 
gtk_tree_model_iter_nth_child (model, &iter, NULL, 3); 
parent_iter = iter; 

gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 
parent_iter = iter; 

gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 
} 


3 


2); 


5); 


This second example shows a quick way of iterating through a list and getting a string and an integer from 
each row. The populate_model function used below is not shown, as it is specific to the GtkListStore. For 
information on how to write such a function, see the GtkListStore documentation. 


Code Example 


enum 


STRING_COLUMN, 
INT_COLUMN, 
N_COLUMNS 

y; 


{ 

GtkTreeModel x*list_store; 
GtkTreeIter iter; 
gboolean valid; 

gint row_count = 0; 


// make a new list_store 
list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, 


Fill the list store with data 
populate_model (list_store); 


// Get the first iter in the list 
valid = gtk_tree_model_get_iter_first (list_store, &iter); 


while (valid) 
{ 
// Walk through the list, reading each row 
gchar xstr_data; 
gint int_data; 


Make sure you terminate calls to gtk_tree_model_get () 
with a ’-1’ value 


G_TYPE_INT); 
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gtk_tree_model_get (list_store, éiter, 
STRING_COLUMN, &str_data, 
INT_COLUMN, &int_data, 
Sa 


// Do something with the data 
g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data); 
g_free (str_data); 


row_count ++; 
valid = gtk_tree_model_iter_next (list_store, 8iter); 


Functions 


GtkTreePath x gtk_tree_path_new (void) 


Creates a new GtkTreePath. 


e GtkTreePath * gtk_tree_path_new_from_string (const gchar *path) 


Creates a new GtkTreePath initialized to path. 


e GtkTreePath * gtk_tree_path_new_from_indices (gint first_index,...) 


Creates a new path with first_index and varargs as indices. 


e gchar * gtk _tree_path_to_string (GtkTreePath xpath) 


Generates a string representation of the path. 


e GtkTreePath x gtk_tree_path_new_first (void) 


Creates a new GtkTreePath. 


e void gtk_tree_path_append_index (GtkTreePath xpath, gint index_) 


Appends a new index to a path. 


e void gtk_tree_path_prepend_index (GtkTreePath xpath, gint index_) 


Prepends a new index to a path. 


e gint gtk_tree_path_get_depth (GtkTreePath xpath) 


Returns the current depth of path. 


e gint * gtk_tree_path_get_indices (GtkTreePath xpath) 


Returns the current indices of path. 


e void gtk_tree_path_free (GtkTreePath *path) 


Frees path. 


e GtkTreePath x gtk_tree_path_copy (const GtkTreePath *path) 


Creates a new GtkTreePath as a copy of path. 


e gint gtk_tree_path_compare (const GtkTreePath xa, const GtkTreePath xb) 


Compares two paths. 
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e void gtk_tree_path_next (GtkTreePath xpath) 


Moves the path to point to the next node at the current depth. 


e gboolean gtk_tree_path_prev (GtkTreePath xpath) 


Moves the path to point to the previous node at the current depth, if it exists. 


e gboolean gtk_tree_path_up (GtkTreePath xpath) 


Moves the path to point to its parent node, if it has a parent. 


e void gtk_tree_path_down (GtkTreePath xpath) 
Moves path to point to the first child of the current path. 


e gboolean gtk_tree_path_is_ancestor (GtkTreePath xpath, GtkTreePath *descendant) 
Returns TRUE if descendant is a descendant of path. 


e gboolean gtk_tree_path_is_descendant (GtkTreePath xpath, GtkTreePath *ancestor) 
Returns TRUE if path is a descendant of ancestor. 


e GtkTreeRowReference * gtk tree_row_reference_new (GtkTreeModel *model, GtkTreePath 
*path) 


Creates a row reference based on path. 


e GtkTreeRowReference * gtk _tree_row_reference_new_proxy (GObject «proxy, GtkTreeModel 
*xmodel, GtkTreePath path) 


Creates a row reference based on path. 


e GtkTreePath x gtk_tree_row_reference_get_path (GtkTreeRowReference «reference) 


Returns a path that the row reference currently points to, or NULL if the path pointed to is no longer valid. 


e GtkTreeModel x gtk_tree_row_reference_get_model (GtkTreeRowReference reference) 


Returns the model that the row reference is monitoring. 


e gboolean gtk_tree_row_reference_valid (GtkTreeRowReference «reference) 


Returns TRUE if the reference is non-NULL and refers to a current valid path. 


e GtkTreeRowReference x gtk_tree_row_reference_copy (GtkTreeRowReference x*reference) 


Copies a GtkTreeRowReference. 


e void gtk_tree_row_reference_free (GtkTreeRowReference «reference) 


Free’s reference. 


e void gtk_tree_row_reference_inserted (GObject «proxy, GtkTreePath *path) 


Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the 
"row_inserted" signal. 


e void gtk_tree_row_reference_deleted (GObject «proxy, GtkTreePath xpath) 


Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the 
"row_deleted" signal. 


e void gtk_tree_row_reference_reordered (GObject «proxy, GtkTreePath «path, GtkTreelter xiter, gint 
*new_order) 
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Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the 
"rows_reordered" signal. 


GtkTreelter x gtk_tree_iter_copy (GtkTreelter xiter) 


Creates a dynamically allocated tree iterator as a copy of iter. 


void gtk_tree_iter_free (GtkTreelter xiter) 


Frees an iterator that has been allocated on the heap. 


GtkTreeModelFlags gtk_tree_model_get_flags (GtkTreeModel *tree_model) 


Returns a set of flags supported by this interface. 


gint gtk_tree_model_get_n_columns (GtkTreeModel xtree_model) 


Returns the number of columns supported by tree_model. 


GType gtk _tree_model_get_column_type (GtkTreeModel *tree_model, gint index_) 


Returns the type of the column. 


gboolean gtk_tree_model_get_iter (GtkTreeModel *tree_model, GtkTreelter xiter, GtkTreePath 
xpath) 


Sets iter to a valid iterator pointing to path. 


gboolean gtk_tree_model_get_iter_from_string (GtkTreeModel »tree_model, GtkTreelter xiter, 
const gchar *path_string) 


Sets iter to a valid iterator pointing to path_string, if it exists. 


gchar * gtk_tree_model_get_string_from_iter (GtkTreeModel xtree_model, GtkTreelter xiter) 


Generates a string representation of the iter. 


gboolean gtk_tree_model_get_iter_first (GtkTreeModel *tree_model, GtkTreelter xiter) 


Initializes iter with the first iterator in the tree (the one at the path "0") and returns TRUE. 


GtkTreePath * gtk_tree_model_get_path (GtkTreeModel *tree_model, GtkTreelter xiter) 


Returns a newly-created GtkTreePath referenced by iter. 


void gtk_tree_model_get_value (GtkTreeModel xtree_model, GtkTreelter xiter, gint column, 
GValue «value) 


Sets initializes and sets value to that at column. 


gboolean gtk_tree_model_iter_next (GtkTreeModel *tree_model, GtkTreelter xiter) 


Sets iter to point to the node following it at the current level. 


gboolean gtk_tree_model_iter_children (GtkTreeModel «tree_model, GtkTreelter xiter, GtkTreelter 
*parent) 


Sets iter to point to the first child of parent. 


gboolean gtk_tree_model_iter_has_child (GtkTreeModel xtree_model, GtkTreelter xiter) 
Returns TRUE if iter has children, FALSE otherwise. 


gint gtk_tree_model_iter_n_children (GtkTreeModel *tree_model, GtkTreelter xiter) 
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Returns the number of children that iter has. 


e gboolean gtk_tree_model_iter_nth_ child (GtkTreeModel x*tree_model, GtkTreelter xiter, Gtk- 
Treelter «parent, gint n) 


Sets iter to be the child of parent, using the given index. 


e gboolean gtk_tree_model_iter_parent (GtkTreeModel x*tree_model, GtkTreelter «iter, GtkTreelter 
*child) 


Sets iter to be the parent of child. 


e void gtk_tree_model_ref_node (GtkTreeModel *tree_model, GtkTreelter «iter) 


This function is primarily meant as a way for views to let caching model know when nodes are being 
displayed (and hence, whether or not to cache that node. 


e void gtk_tree_model_unref_node (GtkTreeModel *tree_model, GtkTreelter xiter) 


Lets the tree unref the node. 


e void gtk_tree_model_get (GtkTreeModel *tree_model, GtkTreelter xiter,...) 


Gets the value of one or more cells in the row referenced by iter. 


e void gtk_tree_model_get_valist (GtkTreeModel *tree_model, GtkTreelter xiter, va_list var_args) 


See gtk_tree_model_get(), this version takes a va_list for language bindings to use. 


e void gtk tree_model foreach (GtkTreeModel *model, GtkTreeModelForeachFunc func, gpointer 
user_data) 


Calls func on each node in model in a depth-first fashion. 


e void gtk tree_model_row_changed (GtkTreeModel *tree_model, GtkTreePath xpath, GtkTreelter 
xiter) 


Emits the "row_changed" signal on tree_model. 


e void gtk_tree_model_row_inserted (GtkTreeModel «tree_model, GtkTreePath «path, GtkTreelter 
xiter) 


Emits the "row_inserted" signal on tree_model. 


e void gtk_tree_model_row_has_child_toggled (GtkTreeModel «tree_model, GtkTreePath «path, Gtk- 
Treelter xiter) 


Emits the "row_has_child_toggled" signal on tree_model. 


e void gtk_tree_model_row_deleted (GtkTreeModel *tree_model, GtkTreePath xpath) 


Emits the "row_deleted" signal on tree_model. 


e void gtk_tree_model_rows_reordered (GtkTreeModel xtree_model, GtkTreePath «path, GtkTreelter 
xiter, gint *new_order) 


Emits the "rows_reordered" signal on tree_model. 


e GtkTreePath * gtk_tree_path_new_last (GtkTreeModel *tree_model) 


Creates a new GtkTreePath. 
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6.49.2 Function Documentation 
6.49.2.1 GtkTreelterx gtk_tree_iter_copy (GtkTreelter x iter) 


Creates a dynamically allocated tree iterator as a copy of iter. 


This function is not intended for use in applications, because you can just copy the structs by value (Gtk- 
Treelter new_iter = iter;). You must free this iter with gtk_tree_iter_free(). 


Parameters: 


iter [in] A GtkTreelter. 


Returns: 


a newly-allocated copy of iter. 


6.49.2.2 void gtk_tree_iter_free (GtkTreelter x iter) 


Frees an iterator that has been allocated on the heap. 


This function is mainly used for language bindings. 


Parameters: 


iter [in] A GtkTreelter. 


Returns: 


void 


6.49.2.3 void gtk_tree_model foreach (GtkTreeModel « model, GtkTreeModelForeachFunc func, 
gpointer user_data) 
Calls func on each node in model in a depth-first fashion. 


If func returns TRUE, then the tree ceases to be walked, and gtk_tree_model_foreach() returns. 


Parameters: 


tree_model [in] A GtkTreeModel. 
func [in] A function to be called on each row 


user_data [in] User data to passed to func. 


Returns: 


void. 


6.49.2.4 void gtk_tree_model_get (GtkTreeModel x tree_model, GtkTreelter x iter, ...) 


Gets the value of one or more cells in the row referenced by iter. 


The variable argument list should contain integer column numbers, each column number followed by a 
place to store the value being retrieved. The list is terminated by a -1. For example, to get a value from 
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column 0 with type G_TYPE_STRING, you would write : gtk_tree_model_get (model, iter, 0, &place_- 
string_here, -1), where place_string_here is a gcharx to be filled with the string. If appropriate, the returned 
values have to be freed or unreferenced. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] a row in tree_model 
. [in] pairs of column number and value return locations, terminated by -1 


Returns: 


void 


6.49.2.5 GType gtk_tree_model_get_column_type (GtkTreeModel x tree_model, gint index_) 


Returns the type of the column. 


Parameters: 


tree_model [in] A GtkTreeModel. 
index_ [in] The column index. 


Returns: 


The column index. 


6.49.2.6 GtkTreeModelFlags gtk_tree_model_get_flags (GtkTreeModel x tree_model) 


Returns a set of flags supported by this interface. 


The flags are a bitwise combination of GtkTreeModelFlags. The flags supported should not change during 
the lifecycle of the tree_model. 


Parameters: 


tree_model [in] A GtkTreeModel. 


Returns: 


The flags supported by this interface. 


6.49.2.7 gboolean gtk_tree_model_get_iter (GtkTreeModel x tree_model, GtkTreelter « iter, 
GtkTreePath x path) 


Sets iter to a valid iterator pointing to path. 


Parameters: 
tree_model [in] A GtkTreeModel. 
iter [in] The uninitialized GtkTreelter. 
path [in] The GtkTreePath. 


Returns: 


TRUE, if iter was set. 
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6.49.2.8 gboolean gtk_tree_model_get_iter_first (GtkTreeModel x tree_model, GtkTreelter x iter) 


Initializes iter with the first iterator in the tree (the one at the path "0") and returns TRUE. 


Returns FALSE if the tree is empty. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] The uninitialized GtkTreelter. 


Returns: 


TRUE, if iter was set. 


6.49.2.9 gboolean gtk_tree_model_get_iter_from_string (GtkTreeModel x tree_model, GtkTreelter 
x iter, const gchar x path_string) 


Sets iter to a valid iterator pointing to path_string, if it exists. 


Otherwise, iter is left invalid and FALSE is returned. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] An uninitialized GtkTreelter. 


path_string [in] A string representation of a GtkTreePath. 


Returns: 


TRUE, if iter was set. 


6.49.2.10 gint gtk_tree_model_get_n columns (GtkTreeModel x tree_model) 


Returns the number of columns supported by tree_model. 


Parameters: 


tree_model [in] A GtkTreeModel. 


Returns: 


The number of columns. 


6.49.2.11 GtkTreePath* gtk_tree_model_get_path (GtkTreeModel = tree_model, GtkTreelter + 
iter) 


Returns a newly-created GtkTreePath referenced by iter. 


This path should be freed with gtk_tree_path_free(). 


Parameters: 


tree_model [in] A GtkTreeModel. 
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iter [in] The GtkTreelter. 


Returns: 


a newly-created GtkTreePath. 


6.49.2.12 gchar» gtk_tree_model get_string_from_iter (GtkTreeModel « tree_model, GtkTreelter 
* iter) 


Generates a string representation of the iter. 


This string is a? : ° separated list of numbers. For example, "4:10:0:3" would be an acceptable return value 
for this string. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] An GtkTreelter. 


Returns: 


A newly-allocated string. Must be freed with g_free(). 


6.49.2.13 void gtk_tree_model_get_valist (GtkTreeModel « tree_model, GtkTreelter x iter, va_list 
var_args) 


See gtk _tree_model_get(), this version takes a va_list for language bindings to use. 


Parameters: 

tree_model [in] A GtkTreeModel. 

iter [in] a row in tree_model 

var_args [in] va_list of column/return location pairs. 
Returns: 


void 


6.49.2.14 void gtk_tree_model_get_value (GtkTreeModel « tree_model, GtkTreelter x iter, gint 
column, GValue x value) 


Sets initializes and sets value to that at column. 


When done with value, g_value_unset() needs to be called to free any allocated memory. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] The GtkTreelter. 
column [in] The column to lookup the value at. 


value [in] An empty GValue to set. 


Returns: 


void 
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6.49.2.15 gboolean gtk_tree_model_iter_children (GtkTreeModel x tree_model, GtkTreelter x iter, 
GtkTreelter x parent) 


Sets iter to point to the first child of parent. 


If parent has no children, FALSE is returned and iter is set to be invalid. parent will remain a valid node 
after this function has been called. If parent is NULL returns the first node, equivalent to gtk_tree_model_- 
get_iter_first (tree_model, iter); 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] The new GtkTreelter to be set to the child. 
parent [in] The GtkTreelter, or NULL 


Returns: 


TRUE, if child has been set to the first child. 


6.49.2.16 gboolean gtk_tree_model_iter_has_child (GtkTreeModel x tree_model, GtkTreelter x 
iter) 


Returns TRUE if iter has children, FALSE otherwise. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] The GtkTreelter to test for children. 


Returns: 


TRUE if iter has children.. 


6.49.2.17 gint gtk_tree_model_iter_n_children (GtkTreeModel x tree_model, GtkTreelter x iter) 


Returns the number of children that iter has. 


As a special case, if iter is NULL, then the number of toplevel nodes is returned. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] The GtkTreelter, or NULL 


Returns: 


The number of children of iter. 


6.49.2.18 gboolean gtk_tree_model_iter_next (GtkTreeModel x tree_model, GtkTreelter + iter) 


Sets iter to point to the node following it at the current level. 


If there is no next iter, FALSE is returned and iter is set to be invalid. 
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Parameters: 
tree_model [in] A GtkTreeModel. 
iter [in] The GtkTreelter. 
Returns: 


TRUE if iter has been changed to the next node. 


6.49.2.19 gboolean gtk_tree_model_iter_nth_child (GtkTreeModel x tree_model, GtkTreelter + 
iter, GtkTreelter * parent, gint n) 


Sets iter to be the child of parent, using the given index. 


The first index is 0. If n is too big, or parent has no children, iter is set to an invalid iterator and FALSE is 
returned. parent will remain a valid node after this function has been called. As a special case, if parent is 
NULL, then the nth root node is set. 


Parameters: 


tree_model [in] A GtkTreeModel. 

iter [in] The GtkTreelter to set to the nth child. 

parent [in] The GtkTreelter to get the child from, or NULL. 
n [in] Then index of the desired child. 


Returns: 


TRUE, if parent has an nth child. 


6.49.2.20  gboolean gtk_tree_model_iter_parent (GtkTreeModel « tree_model, GtkTreelter x iter, 
GtkTreelter x child) 


Sets iter to be the parent of child. 


If child is at the toplevel, and doesn’t have a parent, then iter is set to an invalid iterator and FALSE is 
returned. child will remain a valid node after this function has been called. 


Parameters: 


tree_model [in] A GtkTreeModel. 
iter [in] The new GtkTreelter to set to the parent. 
child [in] The GtkTreelter. 


Returns: 


TRUE, if iter is set to the parent of child. 


6.49.2.21 void gtk_tree_model_ref_node (GtkTreeModel « tree_model, GtkTreelter x iter) 


This function is primarily meant as a way for views to let caching model know when nodes are being 
displayed (and hence, whether or not to cache that node. 


) For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just 
the sections that are currently being displayed by every current view. A model should be expected to be 
able to get an iter independent of its reffed state. 
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Parameters: 
tree_model [in] A GtkTreeModel. 
iter [in] The GtkTreelter. 
Returns: 


void 


6.49.2.22 void gtk_tree_model_row_changed (GtkTreeModel « tree_model, GtkTreePath « path, 
GtkTreelter x iter) 


Emits the "row_changed" signal on tree_model. 


Parameters: 


tree_model [in] A GtkTreeModel. 
path [in] A GtkTreePath pointing to the changed row 
iter [in] A valid GtkTreelter pointing to the changed row 


Returns: 


void 


6.49.2.23 void gtk_tree_model_row_deleted (GtkTreeModel + tree_model, GtkTreePath x path) 


Emits the "row_deleted" signal on tree_model. 


This should be called by models after a row has been removed. The location pointed to by path should be 
the location that the row previously was at. It may not be a valid location anymore. 


Parameters: 

tree_model [in] A GtkTreeModel. 

path [in] A GtkTreePath pointing to the previous location of the deleted row. 
Returns: 


void 


6.49.2.24 void gtk_tree_model_row_has_child_toggled (GtkTreeModel « tree_model, GtkTreePath 
x path, GtkTreelter x iter) 
Emits the "row_has_child_toggled" signal on tree_model. 


This should be called by models after the child state of a node changes. 


Parameters: 
tree_model [in] A GtkTreeModel. 
path [in] A GtkTreePath pointing to the changed row 
iter [in] A valid GtkTreelter pointing to the changed row 
Returns: 


void 
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6.49.2.25 void gtk_tree_model_row_inserted (GtkTreeModel x tree_model, GtkTreePath + path, 
GtkTreelter x iter) 


Emits the "row_inserted" signal on tree_model. 


Parameters: 
tree_model [in] A GtkTreeModel. 
path [in] A GtkTreePath pointing to the inserted row 


iter [in] A valid GtkTreelter pointing to the inserted row 


Returns: 


void 


6.49.2.26 void gtk_tree_model_rows_reordered (GtkTreeModel x tree_model, GtkTreePath * path, 
GtkTreelter x iter, gint x new_order) 


Emits the "rows_reordered" signal on tree_model. 


This should be called by models when their rows have been reordered. 


Parameters: 
tree_model [in] A GtkTreeModel. 
path [in] A GtkTreePath pointing to the tree node whose children have been reordered 


iter [in] A valid GtkTreelter pointing to the node whose children have been reordered, or NULL if the 
depth of path is 0. 


new_order [in] an array of integers mapping the current position of each child to its old position 
before the re-ordering, i.e. new_order[newpos] = oldpos. 


Returns: 


void 


6.49.2.27 void gtk_tree_model_unref_node (GtkTreeModel x tree_model, GtkTreelter x iter) 


Lets the tree unref the node. 
This is an optional method for models to implement. To be more specific, models may ignore this call as it 
exists primarily for performance reasons. 
Parameters: 
tree_model [in] A GtkTreeModel. 
iter [in] The GtkTreelter. 


Returns: 


void 
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6.49.2.28 void gtk_tree_path_append_index (GtkTreePath x path, gint index_) 


Appends a new index to a path. 


As a result, the depth of the path is increased. 


Parameters: 


path [in] A GtkTreePath 


index_ [in] The index. 


Returns: 


void 


6.49.2.29 gint gtk_tree_path_compare (const GtkTreePath « a, const GtkTreePath « b) 


Compares two paths. 


If a appears before b in a tree, then -1 is returned. If b appears before a, then 1 is returned. If the two nodes 
are equal, then 0 is returned. 


Parameters: 


path [in] A GtkTreePath 
b [in] A GtkTreePath to compare with. 


Returns: 


The relative positions of a and b 


6.49.2.30  GtkTreePathx gtk_tree_path_copy (const GtkTreePath x path) 
Creates a new GtkTreePath as a copy of path. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


A new GtkTreePath. 


6.49.2.31 void gtk_tree_path_down (GtkTreePath > path) 
Moves path to point to the first child of the current path. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


void 
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6.49.2.32 void gtk_tree_path_free (GtkTreePath x path) 


Frees path. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


void 


6.49.2.33 gint gtk_tree_path_get_depth (GtkTreePath x path) 
Returns the current depth of path. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


The depth of path 


6.49.2.34 gint» gtk_tree_path_get_indices (GtkTreePath x path) 


Returns the current indices of path. 


This is an array of integers, each representing a node in a tree. This value should not be freed. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


The current indices, or NULL. 


6.49.2.35 gboolean gtk_tree_path_is_ancestor (GtkTreePath + path, GtkTreePath x descendant) 


Returns TRUE if descendant is a descendant of path. 


Parameters: 


path [in] A GtkTreePath 
descendant [in] another GtkTreePath 


Returns: 


TRUE if descendant is contained inside path 
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6.49.2.36 gboolean gtk_tree_path_is_descendant (GtkTreePath + path, GtkTreePath « ancestor) 
Returns TRUE if path is a descendant of ancestor. 


Parameters: 


path [in] A GtkTreePath 


ancestor [in] another GtkTreePath 


Returns: 


TRUE if ancestor contains path somewhere below it 


6.49.2.37 GtkTreePathx gtk_tree_path_new (void) 


Creates a new GtkTreePath. 


This structure refers to a row. 


Returns: 


A newly created GtkTreePath. 


6.49.2.38 GtkTreePathx gtk_tree_path_new_first (void) 


Creates a new GtkTreePath. 


The string representation of this path is "0" 


Returns: 


A new GtkTreePath. 


6.49.2.39 GtkTreePathx gtk_tree_path_new_from_indices (gint first_index, ...) 


Creates a new path with first_index and varargs as indices. 


Parameters: 
path [in] first integer 


. [in] list of integers terminated by -1 


Returns: 


A newly created GtkTreePath. 


6.49.2.40 GtkTreePath« gtk_tree_path_new_from_string (const gchar x path) 


Creates a new GtkTreePath initialized to path. 


path is expected to be a colon separated list of numbers. For example, the string "10:4:0" would create a 
path of depth 3 pointing to the 11th child of the root node, the 5th child of that 11th child, and the Ist child 
of that 5th child. If an invalid path string is passed in, NULL is returned. 
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Parameters: 


path [in] The string representation of a path. 


Returns: 


A newly-created GtkTreePath, or NULL 


6.49.2.41 GtkTreePathx gtk_tree_path_new_last (GtkTreeModel « tree_model) 


Creates a new GtkTreePath. 


The string representation of this path is "0" 


Parameters: 


tree_model [in] A GtkTreeModel. Return value [in] A new GtkTreePath. 


Since 


LIMO R1 


6.49.2.42 void gtk_tree_path_next (GtkTreePath x path) 


Moves the path to point to the next node at the current depth. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


void 


6.49.2.43 void gtk_tree_path_prepend_index (GtkTreePath x path, gint index_) 


Prepends a new index to a path. 


As a result, the depth of the path is increased. 


Parameters: 
path [in] A GtkTreePath 


index_ [in] The index. 


Returns: 


void 
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6.49.2.44 gboolean gtk_tree_path_prev (GtkTreePath x path) 


Moves the path to point to the previous node at the current depth, if it exists. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


TRUE if path has a previous node, and the move was made. 


6.49.2.45 gchar gtk_tree_path_to_string (GtkTreePath x path) 


Generates a string representation of the path. 


This string is a? : ° separated list of numbers. For example, "4:10:0:3" would be an acceptable return value 
for this string. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


A newly-allocated string. Must be freed with g_free(). 


6.49.2.46 gboolean gtk_tree_path_up (GtkTreePath + path) 


Moves the path to point to its parent node, if it has a parent. 


Parameters: 


path [in] A GtkTreePath 


Returns: 


TRUE if path has a parent, and the move was made. 


6.49.2.47 GtkTreeRowReferencex gtk_tree_row_reference_copy (GtkTreeRowReference x 
reference) 


Copies a GtkTreeRowReference. 


Parameters: 


reference [in] A GtkTreeRowReference 


Returns: 


a copy of reference. 
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6.49.2.48 void gtk_tree_row_reference_deleted (GObject « proxy, GtkTreePath x path) 


Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted 
the "row_deleted” signal. 


Parameters: 
proxy [in] A GObject 
path [in] The path position that was deleted 


Returns: 


void 


6.49.2.49 void gtk_tree_row_reference_free (GtkTreeRowReference x reference) 


Free”s reference. 


reference may be NULL. 


Parameters: 


reference [in] A GtkTreeRowReference 


Returns: 


void 


6.49.2.50  GtkTreeModelx gtk_tree_row_reference_get_model (GtkTreeRowReference x reference) 
Returns the model that the row reference is monitoring. 


Parameters: 


reference [in] A GtkTreeRowReference 


Returns: 


the model 


6.49.2.51 GtkTreePathx gtk_tree_row_reference_get_path (GtkTreeRowReference « reference) 


Returns a path that the row reference currently points to, or NULL if the path pointed to is no longer valid. 


Parameters: 


reference [in] A GtkTreeRowReference 


Returns: 


A current path, or NULL. 
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6.49.2.52 void gtk_tree_row_reference_inserted (GObject x proxy, GtkTreePath x path) 


Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted 
the "row_inserted" signal. 
Parameters: 
proxy [in] A GObject 
path [in] The row position that was inserted 
Returns: 


void 


6.49.2.53 GtkTreeRowReferencex gtk_tree_row_reference_new (GtkTreeModel « model, 
GtkTreePath + path) 


Creates a row reference based on path. 


This reference will keep pointing to the node pointed to by path, so long as it exists. It listens to all signals 
emitted by model, and updates its path appropriately. If path isn't a valid path in model, then NULL is 
returned. 


Parameters: 


model [in] A GtkTreeModel 
path [in] A valid GtkTreePath to monitor 


Returns: 


A newly allocated GtkTreeRowReference, or NULL 


6.49.2.54 GtkTreeRowReferencex gtk_tree_row_reference_new_proxy (GObject * proxy, 
GtkTreeModel x model, GtkTreePath x path) 


Creates a row reference based on path. 


This reference will keep pointing to the node pointed to by path, so long as it exists. If path isn't a 
valid path in model, then NULL is returned. However, unlike references created with gtk_tree_row_- 
reference_new(), it does not listen to the model for changes. The creator of the row reference must do 
this explicitly using gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), gtk_tree_row_- 
reference_reordered(). These functions must be called exactly once per proxy when the corresponding 
signal on the model is emitted. This single call updates all row references for that proxy. Since built-in 
GTK+ objects like GtkTree View already use this mechanism internally, using them as the proxy object will 
produce unpredictable results. Further more, passing the same object as model and proxy doesn’t work for 
reasons of internal implementation. 


Parameters: 

proxy [in] A proxy GObject 

model [in] A GtkTreeModel 

path [in] A valid GtkTreePath to monitor 
Returns: 


A newly allocated GtkTreeRowReference, or NULL 
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6.49.2.55 void gtk_tree_row_reference_reordered (GObject x proxy, GtkTreePath x path, 
GtkTreelter x iter, gint x new_order) 


Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted 
the "rows_reordered" signal. 
Parameters: 

proxy [in] A GObject 

path [in] The parent path of the reordered signal 

iter [in] The iter pointing to the parent of the reordered 


new_order [in] The new order of rows 


Returns: 


void 


6.49.2.56 gboolean gtk_tree_row_reference_valid (GtkTreeRowReference x reference) 


Returns TRUE if the reference is non-NULL and refers to a current valid path. 


Parameters: 


reference [in] A GtkTreeRowReference, or NULL 


Returns: 


TRUE if reference points to a valid path. 
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6.50 GtkTreeSelection 


6.50.1 Detailed Description 


The GtkTreeSelection object is a helper object to manage the selection for a GtkTree View widget. 


The GtkTreeSelection object is automatically created when a new GtkTreeView widget is created, and 
cannot exist independentally of this widget. The primary reason the GtkTreeSelection objects exists is for 
cleanliness of code and API. That is, there is no conceptual reason all these functions could not be methods 
on the GtkTreeView widget instead of a separate function. 


The GtkTreeSelection object is gotten from a GtkTreeView by calling gtk_tree_view_get_selection(). It 
can be manipulated to check the selection status of the tree, as well as select and deselect individual rows. 
Selection is done completely view side. As a result, multiple views of the same model can have com- 
pletely different selections. Additionally, you cannot change the selection of a row on the model that is not 
currently displayed by the view without expanding its parents first. 


One of the important things to remember when monitoring the selection of a view is that the "changed" 
signal is mostly a hint. That is, it may only emit one signal when a range of rows is selected. Additionally, 
1t may on occasion emit a "changed" signal when nothing has happened (mostly as a result of programmers 
calling select_row on an already selected row). 


Data Structures 


e struct _GtkTreeSelection 


GtkTreeSelection instance structure. 


e struct _GtkTreeSelectionClass 


GtkTreeSelection instance class structure. 


Functions 


e void gtk_tree_selection_set_mode (GtkTreeSelection selection, GtkSelectionMode type) 


Sets the selection mode of the selection. 


GtkSelectionMode gtk_tree_selection_get_mode (GtkTreeSelection selection) 


Gets the selection mode for selection. 


e void gtk_tree_selection_set_select_function (GtkTreeSelection *selection, GtkTreeSelectionFunc 
func, gpointer data, GtkDestroyNotify destroy) 


Sets the selection function. 


e gpointer gtk_tree_selection_get_user_data (GtkTreeSelection *selection) 


Returns the user data for the selection function. 


GtkTreeView * gtk_tree_selection_get_tree_view (GtkTreeSelection *selection) 


Returns the tree view associated with selection. 


e gboolean gtk_tree_selection_get_selected (GtkTreeSelection *selection, GtkTreeModel *x*model, 
GtkTreelter xiter) 
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Sets iter to the currently selected node if selection is set to GTK_SELECTION_SINGLE or GTK_- 
SELECTION_BROWSE. 


e GList x gtk tree_selection_get_selected_rows (GtkTreeSelection selection, GtkTreeModel 
xxmodel) 


Creates a list of path of all selected rows. 


e gint gtk_tree_selection_count_selected_rows (GtkTreeSelection *selection) 


Returns the number of rows that have been selected in tree. 


e void gtk_tree_selection_selected_foreach (GtkTreeSelection *selection, GtkTreeSelectionForeach- 
Func func, gpointer data) 


Calls a function for each selected node. 


e void gtk_tree_selection_select_path (GtkTreeSelection «selection, GtkTreePath xpath) 


Select the row at path. 


e void gtk_tree_selection_unselect_path (GtkTreeSelection *selection, GtkTreePath «path) 


Unselects the row at path. 


e void gtk_tree_selection_select_iter (GtkTreeSelection *selection, GtkTreelter xiter) 


Selects the specified iterator. 


e void gtk_tree_selection_unselect_iter (GtkTreeSelection «selection, GtkTreelter iter) 


Unselects the specified iterator. 


e gboolean gtk_tree_selection_path_is_selected (GtkTreeSelection *selection, GtkTreePath xpath) 


Returns TRUE if the row pointed to by path is currently selected. 


e gboolean gtk_tree_selection_iter_is_selected (GtkTreeSelection «selection, GtkTreelter xiter) 


Returns TRUE if the row at iter is currently selected. 


e void gtk_tree_selection_select_all (GtkTreeSelection *selection) 


Selects all the nodes. 


e void gtk_tree_selection_unselect_all (GtkTreeSelection *selection) 
Unselects all the nodes. 
e void gtk_tree_selection_select_range (GtkTreeSelection *selection, GtkTreePath x*start_path, Gtk- 
TreePath x*end_path) 
Selects a range of nodes, determined by start_path and end_path inclusive. 


e void gtk tree selection_unselect_range (GtkTreeSelection selection, GtkTreePath xstart_path, 
GtkTreePath x*end_path) 


Unselects a range of nodes, determined by start_path and end_path inclusive. 
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6.50.2 Function Documentation 


6.50.2.1 gint gtk_tree_selection_count_selected_rows (GtkTreeSelection * selection) 


Returns the number of rows that have been selected in tree. 


Parameters: 


selection [in] a GtkTreeSelection 


Returns: 


The number of rows selected. 


6.50.2.2 GtkSelectionMode gtk_tree_selection_get_mode (GtkTreeSelection * selection) 


Gets the selection mode for selection. 


See gtk_tree_selection_set_mode(). 


Parameters: 


selection [in] a GtkTreeSelection 


Returns: 


the current selection mode 


6.50.2.3 gboolean gtk_tree_selection_get_selected (GtkTreeSelection « selection, GtkTreeModel xx 
model, GtkTreelter x iter) 


Sets iter to the currently selected node if selection is set to GTK_SELECTION_SINGLE or GTK_- 
SELECTION_BROWSE. 


iter may be NULL if you just want to test if selection has any selected nodes. model is filled with the 
current model as a convenience. This function will not work if you use selection is GTK_SELECTION_- 
MULTIPLE. 


Parameters: 


selection [in] a GtkTreeSelection 
model [out] A pointer to set to the GtkTreeModel, or NULL. 
iters [out] The GtkTreelter, or NULL. 


Returns: 


TRUE, if there is a selected node. 


6.50.2.4 GList* gtk_tree_selection_get_selected_rows (GtkTreeSelection * selection, 
GtkTreeModel xx model) 


Creates a list of path of all selected rows. 


Additionally, if you are planning on modifying the model after calling this function, you may want to 
convert the returned list into a list of GtkTreeRowReferences. To do this, you can use gtk_tree_row_- 
reference_new(). 
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Parameters: 
selection [in] a GtkTreeSelection 


model [out] A pointer to set to the GtkTreeModel, or NULL. 


Returns: 


A GList containing a GtkTreePath for each selected row. To free the return value, use [in] g_list_- 
foreach (list, gtk_tree_path_free, NULL); g_list_free (list); 


6.50.2.5  GtkTreeViewx gtk_tree_selection_get_tree_view (GtkTreeSelection + selection) 
Returns the tree view associated with selection. 


Parameters: 


selection [in] a GtkTreeSelection 


Returns: 


A GtkTreeView 


6.50.2.6 gpointer gtk_tree_selection_get_user_data (GtkTreeSelection x selection) 
Returns the user data for the selection function. 


Parameters: 


selection [in] a GtkTreeSelection 


Returns: 


The user data. 


6.50.2.7 gboolean gtk_tree_selection_iter_is_selected (GtkTreeSelection x selection, GtkTreelter + 
iter) 


Returns TRUE if the row at iter is currently selected. 
Parameters: 


selection [in] a GtkTreeSelection 


iter [in] A valid GtkTreelter 


Returns: 


TRUE, if iter is selected 
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6.50.2.8 gboolean gtk_tree_selection_path_is_selected (GtkTreeSelection x selection, GtkTreePath 
* path) 


Returns TRUE if the row pointed to by path is currently selected. 
If path does not point to a valid location, FALSE is returned 


Parameters: 


selection [in] a GtkTreeSelection 
path [in] A GtkTreePath to check selection on. 


Returns: 


TRUE if path is selected. 


6.50.2.9 void gtk_tree_selection_select_all (GtkTreeSelection x selection) 


Selects all the nodes. 


selection must be set to GTK_SELECTION_MULTIPLE mode. 


Parameters: 


selection [in] a GtkTreeSelection 


Returns: 


void 


6.50.2.10 void gtk_tree_selection_select_iter (GtkTreeSelection x selection, GtkTreelter x iter) 


Selects the specified iterator. 


Parameters: 


selection [in] a GtkTreeSelection 
iter [in] The GtkTreelter to be selected. 


Returns: 


void 


6.50.2.11 void gtk_tree_selection_select_path (GtkTreeSelection x selection, GtkTreePath + path) 


Select the row at path. 


Parameters: 

selection [in] a GtkTreeSelection 

path [in] The GtkTreePath to be selected. 
Returns: 


void 
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6.50.2.12 void gtk_tree_selection_select_range (GtkTreeSelection x selection, GtkTreePath x 
start_path, GtkTreePath * end_path) 
Selects a range of nodes, determined by start_path and end_path inclusive. 


selection must be set to GTK_SELECTION_MULTIPLE mode. 


Parameters: 
selection [in] a GtkTreeSelection 
start_path [in] The initial node of the range. 


end_path [in] The initial node of the range. 


Returns: 


void 


6.50.2.13 void gtk_tree_selection_selected_foreach (GtkTreeSelection x selection, 
GtkTreeSelectionForeachFunc func, gpointer data) 
Calls a function for each selected node. 
Note that you cannot modify the tree or selection from within this function. As a result, gtk_tree_- 
selection_get_selected_rows() might be more useful. 
Parameters: 
selection [in] a GtkTreeSelection 
funcs [in] The function to call for each selected node. 


data [in] user data to pass to the function. 


Returns: 


void 


6.50.2.14 void gtk_tree_selection_set_mode (GtkTreeSelection x selection, GtkSelectionMode type) 


Sets the selection mode of the selection. 
If the previous type was GTK_SELECTION_MULTIPLE, then the anchor is kept selected, if it was previ- 
ously selected. 
Parameters: 
selection [in] a GtkTreeSelection 


type [in] The selection mode 


Returns: 


void 
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6.50.2.15 void gtk_tree_selection_set_select_function (GtkTreeSelection x selection, 
GtkTreeSelectionFunc func, gpointer data, GtkDestroyNotify destroy) 
Sets the selection function. 


Tf set, this function is called before any node is selected or unselected, giving some control over which 
nodes are selected. The select function should return TRUE if the state of the node may be toggled, and 
FALSE if the state of the node should be left unchanged. 


Parameters: 


selection [in] a GtkTreeSelection 
func [in] The selection function. 
data [in] The selection function’s data. 


destroy [in] The destroy function for user data. May be NULL. 


Returns: 


void 


6.50.2.16 void gtk_tree_selection_unselect_all (GtkTreeSelection x selection) 


Unselects all the nodes. 


Parameters: 


selection [in] a GtkTreeSelection 


Returns: 


void 


6.50.2.17 void gtk_tree_selection_unselect_iter (GtkTreeSelection x selection, GtkTreelter x iter) 
Unselects the specified iterator. 


Parameters: 


selection [in] a GtkTreeSelection 
iter [in] The GtkTreelter to be unselected. 


Returns: 


void 
6.50.2.18 void gtk_tree_selection_unselect_path (GtkTreeSelection x selection, GtkTreePath « 
path) 
Unselects the row at path. 


Parameters: 


selection [in] a GtkTreeSelection 
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path [in] The GtkTreePath to be unselected. 


Returns: 


void 


6.50.2.19 void gtk_tree_selection_unselect_range (GtkTreeSelection « selection, GtkTreePath « 
start_path, GtkTreePath + end_path) 


Unselects a range of nodes, determined by start_path and end_path inclusive. 


Parameters: 


selection [in] a GtkTreeSelection 
start_path [in] The initial node of the range. 
end_path [in] The initial node of the range. 


Returns: 


void 
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6.51 GtkTreeViewColumn 


6.51.1 Detailed Description 


The GtkTreeViewColumn object represents a visible column in a GtkTree View widget. 


It allows to set properties of the column header, and functions as a holding pen for the cell renderers which 


determine how the data in the column is displayed. 


Please refer to the tree widget conceptual overview for an overview of all the objects and data types related 


to the tree widget and how they work together. 


Code Example 


GtkTreeViewColumn *column; 

GtkWidget «tree; 

GtkTreeModel «model; 

model = tree_model_new (); 

tree = gtk_tree_view_new_with_model (model); 

g_object_unref (model); 

column = gtk_tree_view_column_new_with_attributes ("Icon", 
gtk_cell_renderer_pixbuf_new (), 
"stock-id", 0, 


NULL); 
gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column); 
column = gtk_tree_view_column_new_with_attributes ("Index", 

gtk_cell_renderer_text_new (), 

"text", 1, 

NULL); 


gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column); 
gtk_container_add (GTK_CONTAINER (window), tree); 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkTree ViewColumn 


GtkTree ViewColumn instance structure. 


e struct _GtkTree ViewColumnClass 


GTK Native GtkTree ViewColumn instance class structure. 


Typedefs 


e typedef void(* GtkTreeCellDataFunc )(GtkTree ViewColumn *tree_column, GtkCellRenderer cell, 


GtkTreeModel «tree_model, GtkTreelter xiter, gpointer data) 


A function to set the properties of a cell instead of just using the straight mapping between the cell and the 


model. 


Enumerations 


e enum GtkTree ViewColumnSizing 
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The sizing method the column uses to determine its width. 


Functions 


e GtkTreeViewColumn * gtk_tree_view_column_new (void) 


Creates a new GtkTree ViewColumn. 


e GtkTreeViewColumn * gtk_tree_view_column_new_with_attributes (const gchar xtitle, GtkCell- 
Renderer xcell,...) G(GGNUC_NULL_TERMINATED 


Creates a new GtkTreeViewColumn with a number of default values. 


e void gtk_tree_view_column_pack_start (GtkTreeViewColumn *+tree_column, GtkCellRenderer 
«cell, gboolean expand) 


Packs the cell into the beginning of the column. 


e void gtk_tree_view_column_pack_end (Gtk Tree ViewColumn *tree_column, GtkCellRenderer «cell, 
gboolean expand) 


Adds the cell to end of the column. 


e void gtk_tree_view_column_clear (GtkTree ViewColumn *tree_column) 


Unsets all the mappings on all renderers on the tree_column. 


e GList x gtk_tree_view_column_get_cell_renderers (GtkTree ViewColumn xtree_column) 


Returns a newly-allocated GList of all the cell renderers in the column, in no particular order. 


e void gtk_tree_view_column_add_attribute (GtkTree ViewColumn xtree_column, GtkCellRenderer 
*cell_renderer, const gchar xattribute, gint column) 


Adds an attribute mapping to the list in tree_column. 


e void gtk_tree_view_column_set_attributes (GtkTreeViewColumn *tree_column, GtkCellRenderer 
«cell_renderer,...) G_LGNUC_NULL_TERMINATED 


Sets the attributes in the list as the attributes of tree_column. 


e void gtk_tree_view_column_set_cell_data_func (GtkTree ViewColumn *tree_column, GtkCellRen- 
derer *cell_renderer, GtkTreeCellDataFunc func, gpointer func_data, GtkDestroyNotify destroy) 


Sets the GtkTreeViewColumnFunc to use for the column. 


e void gtk_tree_view_column_clear_attributes (GtkTree ViewColumn xtree_column, GtkCellRenderer 
*cell_renderer) 


Clears all existing attributes previously set with gtk_tree_view_column_set_attributes(). 


e void gtk_tree_view_column_set_spacing (GtkTree ViewColumn *tree_column, gint spacing) 


Sets the spacing field of tree_column, which is the number of pixels to place between cell renderers packed 
into it. 


e gint gtk_tree_view_column_get_spacing (GtkTreeViewColumn *tree_column) 


Returns the spacing of tree_column. 


e void gtk_tree_view_column_set_visible (GtkTree ViewColumn »*tree_column, gboolean visible) 
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Sets the visibility of tree_column. 


gboolean gtk_tree_view_column_get_visible (GtkTree ViewColumn x*tree_column) 


Returns TRUE if tree_column is visible. 


void gtk tree_view_column_set_resizable (GtkTreeViewColumn »tree_column, gboolean resiz- 
able) 


If resizable is TRUE, then the user can explicitly resize the column by grabbing the outer edge of the column 
button. 


gboolean gtk_tree_view_column_get_resizable (GtkTree ViewColumn xtree_column) 


Returns TRUE if the tree_column can be resized by the end user. 


void gtk_tree_view_column_set_sizing (GtkTree ViewColumn *tree_column, GtkTree ViewColumn- 
Sizing type) 


Sets the growth behavior of tree_column to type. 


GtkTreeViewColumnSizing gtk_tree_view_column_get_sizing (GtkTreeViewColumn  xtree_- 
column) 


Returns the current type of tree_column. 


gint gtk_tree_view_column_get_width (GtkTree ViewColumn xtree_column) 


Returns the current size of tree_column in pixels. 


gint gtk_tree_view_column_get_fixed_width (GtkTree ViewColumn x*tree_column) 


Gets the fixed width of the column. 


void gtk_tree_view_column_set_fixed_width (GtkTreeViewColumn xtree_column, gint fixed_- 
width) 


Sets the size of the column in pixels. 


void gtk_tree_view_column_set_min_width (GtkTreeViewColumn tree_column, gint min_- 
width) 


Sets the minimum width of the tree_column. 


gint gtk_tree_view_column_get_min_width (GtkTree ViewColumn *tree_column) 


Returns the minimum width in pixels of the tree_column, or -1 if no minimum width is set. 


void gtk_tree_view_column_set_max_width (GtkTreeViewColumn tree_column, gint max_- 
width) 


Sets the maximum width of the tree_column. 


gint gtk_tree_view_column_get_max_width (GtkTreeViewColumn *tree_column) 


Returns the maximum width in pixels of the tree_column, or -1 if no maximum width is set. 


void gtk_tree_view_column_clicked (GtkTree ViewColumn x*tree_column) 


Emits the "clicked" signal on the column. 


void gtk_tree_view_column_set_title (GtkTree ViewColumn x*tree_column, const gchar x*title) 


Sets the title of the tree_column. 
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G_CONST_RETURN gchar x gtk_tree_view_column_get_title (GtkTreeViewColumn xtree_- 
column) 


Returns the title of the widget. 


void gtk_tree_view_column_set_expand (GtkTreeViewColumn *tree_column, gboolean expand) 


Sets the column to take available extra space. 


gboolean gtk_tree_view_column_get_expand (GtkTreeViewColumn *tree_column) 


Return TRUE if the column expands to take any available space. 


void gtk_tree_view_column_set_clickable (GtkTreeViewColumn »tree_column, gboolean click- 
able) 


Sets the header to be active if active is TRUE. 


gboolean gtk_tree_view_column_get_clickable (GtkTree ViewColumn x*tree_column) 


Returns TRUE if the user can click on the header for the column. 


void gtk tree_view_column_set_widget (GtkTreeViewColumn  xtree_column, GtkWidget 
*widget) 


Sets the widget in the header to be widget. 


GtkWidget * gtk_tree_view_column_get_widget (GtkTree ViewColumn xtree_column) 


Returns the GtkWidget in the button on the column header. 


void gtk_tree_view_column_set_alignment (GtkTreeViewColumn *tree_column, gfloat xalign) 


Sets the alignment of the title or custom widget inside the column header. 


gfloat gtk_tree_view_column_get_alignment (GtkTree ViewColumn *tree_column) 


Returns the current x alignment of tree_column. 


void gtk_tree_view_column_set_reorderable (GtkTreeViewColumn *tree_column, gboolean re- 
orderable) 


If reorderable is TRUE, then the column can be reordered by the end user dragging the header. 


gboolean gtk_tree_view_column_get_reorderable (GtkTree ViewColumn *tree_column) 


Returns TRUE if the tree_column can be reordered by the user. 


void gtk_tree_view_column_set_sort_column_id (GtkTreeViewColumn *tree_column, gint sort_- 
column_id) 


You probably only want to use gtk_tree_view_column_set_sort_column_id. 


gint gtk_tree_view_column_get_sort_column_id (GtkTree ViewColumn *tree_column) 


Gets the value set by gtk_tree_view_column_set_sort_indicator(). 


void gtk_tree_view_column_set_sort_indicator (GtkTreeViewColumn *tree_column, gboolean set- 
ting) 
Call this function with a setting of TRUE to display an arrow in the header button indicating the column is 
sorted. 


gboolean gtk_tree_view_column_get_sort_indicator (GtkTreeViewColumn *tree_column) 
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Gets the value set by gtk_tree_view_column_set_sort_indicator(). 


e void gtk_tree_view_column_set_sort_order (GtkTree ViewColumn *tree_column, GtkSortType or- 
der) 


Changes the appearance of the sort indicator. 


e GtkSortType gtk_tree_view_column_get_sort_order (GtkTree ViewColumn *tree_column) 


Gets the value set by gtk_tree_view_column_set_sort_order(). 


e void gtk_tree_view_column_cell_set_cell_data (GtkTreeViewColumn  x*xtree_column, Gtk- 
TreeModel «tree_model, GtkTreelter xiter, gboolean is_expander, gboolean is_expanded) 


Sets the cell renderer based on the tree_model and iter. 


e void gtk_tree_view_column_cell_get_size (GtkTreeViewColumn *tree_column, GdkRectangle 
*cell_area, gint *x_offset, gint *y_offset, gint «width, gint *height) 


Obtains the width and height needed to render the column. 


e gboolean gtk_tree_view_column_cell_is_visible (GtkTreeViewColumn »*tree_column) 


Returns TRUE if any of the cells packed into the tree_column are visible. 


e void gtk_tree_view_column_focus_cell (GtkTreeViewColumn »xtree_column, GtkCellRenderer 
*cell) 


Sets the current keyboard focus to be at cell, ifthe column contains 2 or more editable and activatable cells. 


e gboolean gtk_tree_view_column_cell_get_position (GtkTree ViewColumn xtree_column, GtkCell- 
Renderer *cell_renderer, gint *start_pos, gint *width) 


Obtains the horizontal position and size of a cell in a column. 


e void gtk_tree_view_column_queue_resize (GtkTree ViewColumn *tree_column) 


Flags the column, and the cell renderers added to this column, to have their sizes renegotiated.s. 


6.51.2 Typedef Documentation 


6.51.2.1 typedef void(« GtkTreeCellDataFunc)(GtkTree ViewColumn «tree_column, 
GtkCellRenderer cell, GtkTreeModel «tree_model, GtkTreelter «iter, gpointer data) 


A function to set the properties of a cell instead of just using the straight mapping between the cell and the 
model. 


This is useful for customizing the cell renderer. For example, a function might get an integer from the 
tree_model, and render it to the "text" attribute of "cell" by converting it to its written equivilent. This is 
set by calling gtk_tree_view_column_set_cell_data_func() 


Parameters: 


tree_column [in] A GtkTreeColumn 

cell [in] The GtkCellRenderer that is being rendered by tree_column . 
tree_model [in] The GtkTreeModel being rendered . 

iter [in] A GtkTreelter of the current row rendered 


data [in] user data 
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Returns: 

void 
6.51.3 Enumeration Type Documentation 
6.51.3.1 enum GtkTreeViewColumnSizing 


The sizing method the column uses to determine its width. 


Please note that GTK_TREE_VIEW_COLUMN_AUTOSIZE are inefficient for large views, and can make 
columns appear choppy. 


6.51.4 Function Documentation 


6.51.4.1 void gtk_tree_view_column_add_attribute (GtkTree ViewColumn > tree_column, 
GtkCellRenderer x cell_renderer, const gchar x attribute, gint column) 


Adds an attribute mapping to the list in tree_column. 


The column is the column of the model to get a value from, and the attribute is the parameter on cell_- 
renderer to be set from the value. So for example 1f column 2 of the model contains strings, you could have 
the "text" attribute of a GtkCellRendererText get its values from column 2. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
cell_renderer [in] the GtkCellRenderer to set attributes on 
attribute [in] An attribute on the renderer 


column [in] The column position on the model to get the attribute from. 


Returns: 


void 


6.51.4.2 gboolean gtk_tree_view_column_cell_get_position (GtkTreeViewColumn = tree_column, 
GtkCellRenderer x cell_renderer, gint x start_pos, gint * width) 


Obtains the horizontal position and size of a cell in a column. 


Tf the cell is not found in the column, start_pos and width are not changed and FALSE is returned. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
cell_renderer [in] a GtkCellRenderer 
start_pos [out] return location for the horizontal position of cell within tree_column, may be NULL 


width [out] return location for the width of cell, may be NULL 


Returns: 


TRUE if cell belongs to tree_column. 
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6.51.4.3 void gtk_tree_view_column_cell_get_size (GtkTree ViewColumn x tree_column, 
GdkRectangle + cell_area, gint « x_offset, gint x y_offset, gint x width, gint x height) 


Obtains the width and height needed to render the column. 


This is used primarily by the GtkTreeView. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 

cell_area [in] The area a cell in the column will be allocated, or NULL 
x_offset [out] location to return x offset of a cell relative to cell_area, or NULL 
y_offset [out] location to return y offset of a cell relative to cell_area, or NULL 
width [out] location to return width needed to render a cell, or NULL 

height [out] location to return height needed to render a cell, or NULL 


Returns: 


void 


6.51.4.4 gboolean gtk_tree_view_column_cell_is_visible (GtkTreeViewColumn = tree_column) 


Returns TRUE if any of the cells packed into the tree_column are visible. 


For this to be meaningful, you must first initialize the cells with gtk_tree_view_column_cell_set_cell_- 
data() 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


TRUE, if any of the cells packed into the tree_column are currently visible 


6.51.4.5 void gtk_tree_view_column_cell_set_cell_data (GtkTree ViewColumn = tree_column, 
GtkTreeModel x tree_model, GtkTreelter x iter, gboolean is_expander, gboolean 
is_expanded) 


Sets the cell renderer based on the tree_model and iter. 

That is, for every attribute mapping in tree_column, it will get a value from the set column on the iter, and 
use that value to set the attribute on the cell renderer. This is used primarily by the GtkTree View. 
Parameters: 


tree_column [in] a GtkTree ViewColumn 

tree_model [in] The GtkTreeModel to to get the cell renderers attributes from. 
iter [in] The GtkTreelter to to get the cell renderer’s attributes from. 
is_expander [in] TRUE, if the row has children 

is_expanded [in] TRUE, if the row has visible children 


Returns: 


void 
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6.51.4.6 void gtk_tree_view_column_clear (GtkTreeViewColumn = tree_column) 


Unsets all the mappings on all renderers on the tree_column. 


Parameters: 


tree_column [in] A GtkTreeViewColumn 


Returns: 


void 


6.51.4.7 void gtk_tree_view_column_clear_attributes (GtkTree ViewColumn x tree_column, 
GtkCellRenderer x cell_renderer) 


Clears all existing attributes previously set with gtk_tree_view_column_set_attributes(). 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


cell_renderer [in] a GtkCellRenderer to clear the attribute mapping on. 


Returns: 


void 


6.51.4.8 void gtk_tree_view_column_clicked (GtkTreeViewColumn > tree_column) 


Emits the "clicked" signal on the column. 


This function will only work if tree_column is clickable. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


void 


6.51.4.9 void gtk_tree_view_column_focus_cell (GtkTreeViewColumn = tree_column, 
GtkCellRenderer « cell) 


Sets the current keyboard focus to be at cell, if the column contains 2 or more editable and activatable cells. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
cell [in] A GtkCellRenderer 


Returns: 


void 
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6.51.4.10  gfloat gtk_tree_view_column_get_alignment (GtkTreeViewColumn = tree_column) 


Returns the current x alignment of tree_column. 


This value can range between 0.0 and 1.0. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


The current alignent of tree_column. 


6.51.4.11 GList« gtk_tree_view_column_get_cell_renderers (GtkTreeViewColumn = tree_column) 


Returns a newly-allocated GList of all the cell renderers in the column, in no particular order. 


The list must be freed with g_list_free(). 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


A list of GtkCellRenderers 


6.51.4.12 gboolean gtk_tree_view_column_get_clickable (GtkTree ViewColumn = tree_column) 


Returns TRUE if the user can click on the header for the column. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


TRUE if user can click the column header. 


6.51.4.13 gboolean gtk_tree_view_column_get_expand (GtkTreeViewColumn = tree_column) 


Return TRUE if the column expands to take any available space. 


Parameters: 


tree_column [in] a GtkTreeViewColumnp 


Returns: 


TRUE, if the column expands 
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6.51.4.14 gint gtk_tree_view_column_get_fixed_width (GtkTreeViewColumn = tree_column) 


Gets the fixed width of the column. 


This value is only meaning may not be the actual width of the column on the screen, just what is re- 
quested. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


the fixed width of the column 


6.51.4.15 gint gtk_tree_view_column_get_max_width (GtkTreeViewColumn = tree_column) 


Returns the maximum width in pixels of the tree_column, or -1 if no maximum width is set. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


The maximum width of the tree_column. 


6.51.4.16 gint gtk_tree_view_column_get_min_width (GtkTreeViewColumn + tree_column) 


Returns the minimum width in pixels of the tree_column, or -1 if no minimum width is set. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


The minimum width of the tree_column. 


6.51.4.17 gboolean gtk_tree_view_column_get_reorderable (GtkTree ViewColumn = tree_column) 


Returns TRUE if the tree_column can be reordered by the user. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


TRUE if the tree_column can be reordered by the user. 
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6.51.4.18 gboolean gtk_tree_view_column_get_resizable (GtkTree ViewColumn + tree_column) 


Returns TRUE if the tree_column can be resized by the end user. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


TRUE, if the tree_column can be resized. 


6.51.4.19 GtkTreeViewColumnSizing gtk_tree_view_column_get_sizing (GtkTreeViewColumn * 
tree_column) 


Returns the current type of tree_column. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


The type of tree_column. 


6.51.4.20 gint gtk_tree_view_column_get_sort_column_id (GtkTree ViewColumn x tree_column) 


Gets the value set by gtk_tree_view_column_set_sort_indicator(). 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


the current sort_column_id for this column, or -1 if this column can’t be used for sorting. 


6.51.4.21 gboolean gtk_tree_view_column_get_sort_indicator (GtkTree ViewColumn x 
tree_column) 


Gets the value set by gtk_tree_view_column_set_sort_indicator(). 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


whether the sort indicator arrow is displayed 
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6.51.4.22 GtkSortType gtk_tree_view_column_get_sort_order (GtkTreeViewColumn * 
tree_column) 


Gets the value set by gtk_tree_view_column_set_sort_order(). 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


the sort order the sort indicator is indicating 


6.51.4.23 gint gtk_tree_view_column_get_spacing (GtkTree ViewColumn = tree_column) 


Returns the spacing of tree_column. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


the spacing of tree_column. 


6.51.4.24 G_CONST_RETURN gchar» gtk_tree_view_column_get_title (GtkTreeViewColumn = 
tree_column) 


Returns the title of the widget. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


the title of the column. This string should not be modified or freed. 


6.51.4.25 gboolean gtk_tree_view_column_get_visible (GtkTree ViewColumn = tree_column) 


Returns TRUE if tree_column is visible. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


whether the column is visible or not. If it is visible, then the tree will show the column. 
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6.51.4.26 GtkWidget« gtk_tree_view_column_get_widget (GtkTree ViewColumn « tree_column) 


Returns the GtkWidget in the button on the column header. 


If a custom widget has not been set then NULL is returned. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


The GtkWidget in the column header, or NULL 


6.51.4.27 gint gtk_tree_view_column_get_width (GtkTreeViewColumn = tree_column) 


Returns the current size of tree_column in pixels. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


Returns: 


The current width of tree_column. 


6.51.4.28 GtkTreeViewColumnx gtk_tree_view_column_new (void) 


Creates a new GtkTree ViewColumn. 


Returns: 


A newly created GtkTree ViewColumn. 


6.51.4.29 GtkTreeViewColumnx gtk_tree_view_column_new_with_attributes (const gchar « title, 
GtkCellRenderer x cell, ...) 


Creates a new GtkTree ViewColumn with a number of default values. 


This is equivalent to calling gtk_tree_view_column_set_title(), gtk_tree_view_column_pack_start(), and 
gtk_tree_view_column_set_attributes() on the newly created GtkTreeViewColumn. 


Here's a simple example: 


enum { TEXT_COLUMN, COLOR_COLUMN, N_COLUMNS ); 
{ 


GtkTreeViewColumn *column; 


GtkCellRenderer *renderer = gtk_cell_renderer_text_new (); 
column = gtk_tree_view_column_new_with_attributes ("Title", 
renderer, 


"text", TEXT_COLUMN, 
"foreground", COLOR_COLUMN, 
NULL); 
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Parameters: 


title [in] The title to set the header to. 
cell [in] The GtkCellRenderer. 
. [in] A NULL-terminated list of attributes. 


Returns: 


A newly created GtkTree ViewColumn. 


6.51.4.30 void gtk_tree_view_column_pack_end (GtkTreeViewColumn = tree_column, 
GtkCellRenderer + cell, gboolean expand) 


Adds the cell to end of the column. 


If expand is FALSE, then the cell is allocated no more space than it needs. Any unused space is divided 
evenly between cells for which expand is TRUE. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
cell [in] The GtkCellRenderer. 


expand [in] TRUE if cell is to be given extra space allocated to tree_column. 


Returns: 


void 


6.51.4.31 void gtk_tree_view_column_pack_start (GtkTree ViewColumn + tree_column, 
GtkCellRenderer x cell, gboolean expand) 


Packs the cell into the beginning of the column. 


If expand is FALSE, then the cell is allocated no more space than it needs. Any unused space is divided 
evenly between cells for which expand is TRUE. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
cell [in] The GtkCellRenderer. 


expand [in] TRUE if cell is to be given extra space allocated to tree_column. 


Returns: 


void 


6.51.4.32 void gtk_tree_view_column_queue_resize (GtkTreeViewColumn x tree_column) 


Flags the column, and the cell renderers added to this column, to have their sizes renegotiated.s. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
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Returns: 


void 


6.51.4.33 void gtk_tree_view_column_set_alignment (GtkTreeViewColumn = tree_column, gfloat 
xalign) 


Sets the alignment of the title or custom widget inside the column header. 


The alignment determines its location inside the button — 0.0 for left, 0.5 for center, 1.0 for right. 


Parameters: 
tree_column [in] a GtkTree ViewColumn 


xalign [in] The alignment, which is between [0.0 and 1.0] inclusive. 


Returns: 


void 


6.51.4.34 void gtk_tree_view_column_set_attributes (GtkTreeViewColumn « tree_column, 
GtkCellRenderer x cell_renderer, ...) 


Sets the attributes in the list as the attributes of tree_column. 


The attributes should be in attribute/column order, as in gtk_tree_view_column_add_attribute(). All exist- 
ing attributes are removed, and replaced with the new attributes. 


Parameters: 
tree_column [in] a GtkTree ViewColumn 
cell_renderer [in] the GtkCellRenderer we're setting the attributes of 


... [in] A NULL-terminated list of attributes. 


Returns: 


void 


6.51.4.35 void gtk_tree_view_column_set_cell_data_func (GtkTreeViewColumn x tree_column, 
GtkCellRenderer x cell_renderer, GtkTreeCellDataFunc func, gpointer func_data, 
GtkDestroyNotify destroy) 


Sets the GtkTreeViewColumnFunc to use for the column. 

This function is used instead of the standard attributes mapping for setting the column value, and should 
set the value of tree_column’s cell renderer as appropriate. func may be NULL to remove an older one. 
Parameters: 


tree_column [in] a GtkTree ViewColumn 
cell_renderer [in] A GtkCellRenderer 


func [in] The GtkTree ViewColumnFunc to use. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.51 GtkTree ViewColumn 509 


func_data [in] The user data for func. 


destroy [in] The destroy notification for func_data 


Returns: 


void 


6.51.4.36 void gtk_tree_view_column_set_clickable (GtkTree ViewColumn > tree_column, 
gboolean clickable) 


Sets the header to be active if active is TRUE. 


When the header is active, then it can take keyboard focus, and can be clicked. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
clickable [in] TRUE if the header is active. 


Returns: 


void 


6.51.4.37 void gtk_tree_view_column_set_expand (GtkTreeViewColumn = tree_column, gboolean 
expand) 


Sets the column to take available extra space. 


This space is shared equally amongst all columns that have the expand set to TRUE. If no column has 
this option set, then the last column gets all extra space. By default, every column is created with this 
FALSE. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


expand [in] TRUE if the column should take available extra space, FALSE if not 


Returns: 


void 


6.51.4.38 void gtk_tree_view_column_set_fixed_width (GtkTreeViewColumn + tree_column, gint 
fixed_width) 


Sets the size of the column in pixels. 


This is meaningful only if the sizing type is GTK_TREE_VIEW_COLUMN_FIXED. The size of the col- 
umn is clamped to the min/max width for the column. Please note that the min/max width of the column 
doesn’t actually affect the "fixed_width" property of the widget, just the actual size when displayed. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
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fixed_width [in] The size to set tree_column to. Must be greater than 0. 


Returns: 


void 


6.51.4.39 void gtk_tree_view_column_set_max_ width (GtkTreeViewColumn = tree_column, gint 
max_width) 


Sets the maximum width of the tree_column. 


If max_width is -1, then the maximum width is unset. Note, the column can actually be wider than max 
width if it’s the last column in a view. In this case, the column expands to fill any extra space. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


max_width [in] The maximum width of the column in pixels, or -1. 


Returns: 


void 


6.51.4.40 void gtk_tree_view_column_set_min_ width (GtkTreeViewColumn = tree_column, gint 
min_width) 
Sets the minimum width of the tree_column. 


If min_width is -1, then the minimum width is unset. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


min_width [in] The minimum width of the column in pixels, or -1. 


Returns: 


void 


6.51.4.41 void gtk_tree_view_column_set_reorderable (GtkTreeViewColumn  tree_column, 
gboolean reorderable) 


If reorderable is TRUE, then the column can be reordered by the end user dragging the header. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


reorderable [in] TRUE, if the column can be reordered. 


Returns: 


void 
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6.51.4.42 void gtk_tree_view_column_set_resizable (GtkTreeViewColumn = tree_column, 
gboolean resizable) 


If resizable is TRUE, then the user can explicitly resize the column by grabbing the outer edge of the 
column button. 


If resizable is TRUE and sizing mode of the column is GTK_TREE_VIEW_COLUMN_AUTOSIZE, then 
the sizing mode is changed to GTK_TREE_VIEW_COLUMN_GROW_ONLY. 
Parameters: 

tree_column [in] a GtkTree ViewColumn 


resizable [in] TRUE, if the column can be resized 


Returns: 


void 


6.51.4.43 void gtk_tree_view_column_set_sizing (GtkTree ViewColumn = tree_column, 
GtkTreeViewColumnSizing type) 


Sets the growth behavior of tree_column to type. 


Parameters: 
tree_column [in] a GtkTree ViewColumn 


type [in] The GtkTree ViewColumnSizing. 


Returns: 


void 


6.51.4.44 void gtk_tree_view_column_set_sort_column_id (GtkTreeViewColumn x tree_column, 
gint sort_column_id) 


You probably only want to use gtk_tree_view_column_set_sort_column_id. 


The other sorting functions exist primarily to let others do their own custom sorting. Sets the logical sort_- 
column_id that this column sorts on when this column is selected for sorting. Doing so makes the column 
header clickable. 
Parameters: 

tree_column [in] a GtkTree ViewColumn 


sort_column_id [in] The sort_column_id of the model to sort on. 


Returns: 


void 
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6.51.4.45 void gtk_tree_view_column_set_sort_indicator (GtkTreeViewColumn > tree_column, 
gboolean setting) 


Call this function with a setting of TRUE to display an arrow in the header button indicating the column is 
sorted. 


Call gtk_tree_view_column_set_sort_order() to change the direction of the arrow. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


setting [in] TRUE to display an indicator that the column is sorted 


Returns: 


void 


6.51.4.46 void gtk_tree_view_column_set_sort_order (GtkTreeViewColumn = tree_column, 
GtkSortType order) 


Changes the appearance of the sort indicator. 


This does not actually sort the model. Use gtk_tree_view_column_set_sort_column_id() if you want au- 
tomatic sorting support. This function is primarily for custom sorting behavior, and should be used in 
conjunction with gtk_tree_sortable_set_sort_column() to do that. For custom models, the mechanism will 


vary. 
The sort indicator changes direction to indicate normal sort or reverse sort. Note that you must have the 


sort indicator enabled to see anything when calling this function; see gtk_tree_view_column_set_sort_- 
indicator(). 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


order [in] sort order that the sort indicator should indicate 


Returns: 


void 


6.51.4.47 void gtk_tree_view_column_set_spacing (GtkTree ViewColumn = tree_column, gint 
spacing) 


Sets the spacing field of tree_column, which is the number of pixels to place between cell renderers packed 
into it. 
Parameters: 


tree_column [in] a GtkTree ViewColumn 


spacing [in] distance between cell renderers in pixels. 


Returns: 


void 
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6.51.4.48 void gtk_tree_view_column_set_title (GtkTreeViewColumn = tree_column, const gchar + 
title) 


Sets the title of the tree_column. 


If a custom widget has been set, then this value is ignored. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


title [in] The title of the tree_column. 


Returns: 


void 


6.51.4.49 void gtk_tree_view_column_set_visible (GtkTreeViewColumn + tree_column, gboolean 
visible) 


Sets the visibility of tree_column. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 


visible [in] TRUE if the tree_column is visible. 


Returns: 


void 


6.51.4.50 void gtk_tree_view_column_set_widget (GtkTreeViewColumn x tree_column, 
GtkWidget x widget) 


Sets the widget in the header to be widget. 


If widget is NULL, then the header button is set with a GtkLabel set to the title of tree_column. 


Parameters: 


tree_column [in] a GtkTree ViewColumn 
widget [in] A child GtkWidget, or NULL. 


Returns: 


void 
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6.52 GtkTreeview 


6.52.1 Detailed Description 


Widget that displays any object that implements the GtkTreeModel interface. 


Please refer to the tree widget conceptual overview for an overview of all the objects and data types related 
to the tree widget and how they work together. 


GtkTreeview Widget modified to for Mobile environment. Is inheritted from GtkTreeView and Modified 
for style of mobile UI 


Treevie 


Milan 


withoowith 


Figure 6.12: GtkTree View 


Code Example 


GtkWidget «tree; 

GtkWidget «sw; 

GtkTreeModel «model; 

GtkTreeViewColumn «column; 

sw = gtk_scrolled_window_new (NULL, NULL); 

gtk_scrolled_window_set_shadow_type (GTK_SCROLLED_WINDOW (sw), 
GTK_SHADOW_IN) ; 


model = tree_model_new (); 

tree = gtk_tree_view_new_with_model (model); 

g_object_unref (model); 

gtk_widget_set_size_request (tree, 300, 100); 

column = gtk_tree_view_column_new_with_attributes ("Icon", 
gtk_cell_renderer_pixbuf_new (), 
"stock-id", 0, 
NULL); 

gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column); 
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column = gtk_tree_view_column_new_with_attributes ("Index", 
gtk_cell_renderer_text_new (), 
"text", 1, 
NULL); 

gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column); 

column = gtk_tree_view_column_new_with_attributes ("Canterbury Tales", 
gtk_cell_renderer_text_new (), 
"text", 2, 
NULL); 


gtk_tree_view_append_column (GTK_TREE_VIEW (tree), column); 
gtk_container_add (GTK_CONTAINER (sw), tree); 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkTree View 


GtkTree View instance structure. 


e struct _GtkTree ViewClass 


GTK Native GtkTreeView instance class structure. 


Typedefs 


e typedef gboolean(* GtkTreeViewColumnDropFunc )(GtkTreeView «*tree_view, GtkTreeViewCol- 
umn *column, GtkTreeViewColumn *prev_column, GtkTreeViewColumn *next_column, gpointer 
data) 


Function type for determining whether column can be dropped in a particular spot (as determined by prev_- 
column and next_column). 


e typedef void(« GtkTreeViewMappingFunc )(GtkTreeView *tree_view, GtkTreePath «path, gpointer 
user_data) 


Function used for gtk_tree_view_map_expanded_rows. 


e typedef gboolean(* GtkTreeViewSearchEqualFunc )(GtkTreeModel «model, gint column, const 
gchar «key, GtkTreelter xiter, gpointer search_data) 


A function used for checking whether a row in model matches a search key string entered by the user. 


e typedef gboolean(* GtkTreeViewRowSeparatorFunc )(GtkTreeModel *model, GtkTreelter xiter, 
gpointer data) 


Function type for determining whether the row pointed to by iter should be rendered as a separator. 


e typedef void(* GtkTreeViewSearchPositionFunc )(GtkTreeView +tree_view, GtkWidget *search_- 
dialog, gpointer user_data) 


Function used to Tree View Position Func. 


e typedef void(* GtkTreeDestroyCountFunc )(GtkTree View *tree_view, GtkTreePath xpath, gint chil- 
dren, gpointer user_data) 


destroys the tree view count function 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


516 Module Documentation 


Functions 


e GtkWidget * gtk_tree_view_new (void) 


Creates a new GtkTreeView widget. 


e GtkWidget * gtk_tree_view_new_with_model (GtkTreeModel «model) 


Creates a new GtkTreeView widget with the model initialized to model. 


e GtkTreeModel x gtk_tree_view_get_model (GtkTreeView *tree_view) 


Returns the model the GtkTreeView is based on. 


e void gtk_tree_view_set_model (GtkTree View x*tree_view, GtkTreeModel x*model) 


Sets the model for a GtkTreeView. 


e GtkTreeSelection * gtk_tree_view_get_selection (GtkTreeView *tree_view) 


Gets the GtkTreeSelection associated with tree_view. 


e GtkAdjustment * gtk_tree_view_get_hadjustment (GtkTreeView *tree_view) 


Gets the GtkAdjustment currently being used for the horizontal aspect. 


e void gtk_tree_view_set_hadjustment (GtkTree View x*tree_view, GtkAdjustment *adjustment) 


Sets the GtkAdjustment for the current horizontal aspect. 


e GtkAdjustment * gtk_tree_view_get_vadjustment (GtkTreeView xtree_view) 


Gets the GtkAdjustment currently being used for the vertical aspect. 


e void gtk_tree_view_set_vadjustment (GtkTree View x*tree_view, GtkAdjustment *adjustment) 


Sets the GtkAdjustment for the current vertical aspect. 


e gboolean gtk_tree_view_get_headers_visible (GtkTreeView *tree_view) 


Returns TRUE if the headers on the tree_view are visible. 


e void gtk_tree_view_set_headers_visible (GtkTreeView *+tree_view, gboolean headers_visible) 


Sets the visibility state of the headers. 


e void gtk_tree_view_columns_autosize (GtkTreeView xtree_view) 


Resizes all columns to their optimal width. 


e gboolean gtk_tree_view_get_headers_clickable (GtkTreeView x*tree_view) 


[Deprecated] Returns whether all header columns are clickable. 


e void gtk_tree_view_set_headers_clickable (GtkTreeView xtree_view, gboolean setting) 


[Deprecated] Allow the column title buttons to be clicked. 


e void gtk_tree_view_set_rules_hint (GtkTreeView xtree_view, gboolean setting) 


This function tells GTK+ that the user interface for your application requires users to read across tree rows 
and associate cells with one another. 


e gboolean gtk_tree_view_get_rules_hint (GtkTree View *tree_view) 


Gets the setting set by gtk_tree_view_set_rules_hint(). 
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e gint gtk_tree_view_append_column (GtkTreeView *tree_view, GtkTree ViewColumn *column) 


Appends column to the list of columns. 


e gint gtk_tree_view_remove_column (GtkTreeView x*tree_view, GtkTree ViewColumn *column) 


Removes column from tree_view. 


e gint gtk_tree_view_insert_column (GtkTreeView *tree_view, GtkTree ViewColumn *column, gint 
position) 


This inserts the column into the tree_view at position. 


e gint gtk_tree_view_insert_column_with_attributes (GtkTreeView x*tree_view, gint position, const 
gchar xtitle, GtkCellRenderer xcell,...) G_GNUC_NULL_TERMINATED 


Creates a new GtkTreeViewColumn and inserts it into the tree_view at position. 


e gint gtk_tree_view_insert_column_with_data_func (GtkTreeView x*tree_view, gint position, const 
gchar xtitle, GtkCellRenderer x*cell, GtkTreeCellDataFunc func, gpointer data, GDestroyNotify dno- 


tify) 
Convenience function that inserts a new column into the GtkTreeView with the given cell renderer and a 
GtkCellDataFunc to set cell renderer attributes (normally using data from the model). 


e GtkTreeViewColumn * gtk_tree_view_get_column (GtkTreeView x*tree_view, gint n) 


Gets the GtkTree ViewColumn at the given position in the tree_view. 


e GList * gtk_tree_view_get_columns (GtkTree View *tree_view) 


Returns a GList of all the GtkTreeViewColumn s currently in tree_view. 


e void gtk_tree_view_move_column_after (GtkTreeView x*tree_view, GtkTreeViewColumn «column, 
GtkTree ViewColumn *base_column) 


Moves column to be after to base_column. 


e void gtk _tree_view_set_expander_column (GtkTreeView  xtree_view, GtkTreeViewColumn 
*column) 


Sets the column to draw the expander arrow at. 


e GtkTreeViewColumn * gtk_tree_view_get_expander_column (GtkTreeView *tree_view) 


Returns the column that is the current expander column. 


e void gtk_tree_view_set_column_drag_function (GtkTreeView *+tree_view, GtkTreeViewColumn- 
DropFunc func, gpointer user_data, GtkDestroyNotify destroy) 


[Deprecated] Sets a user function for determining where a column may be dropped when dragged.This 
function is called on every column pair in turn at the beginning of a column drag to determine where a drop 
can take place. 


e void gtk_tree_view_scroll_to_point (GtkTreeView «*tree_view, gint tree_x, gint tree_y) 


Scrolls the tree view such that the top-left corner of the visible area is tree_x, tree_y, where tree_x and tree_y 
are specified in tree window coordinates. 


e void gtk_tree_view_scroll_to_cell (GtkTreeView *tree_view, GtkTreePath xpath, GtkTree ViewCol- 
umn «column, gboolean use_align, gfloat row_align, gfloat col_align) 


Moves the alignments of tree_view to the position specified by column and path. 
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void gtk_tree_view_row_activated (GtkTree View xtree_view, GtkTreePath xpath, GtkTree ViewCol- 
umn *column) 


Activates the cell determined by path and column. 


void gtk_tree_view_expand_all (GtkTreeView *tree_view) 


Recursively expands all nodes in the tree_view. 


void gtk_tree_view_collapse_all (GtkTreeView xtree_view) 


Recursively collapses all visible, expanded nodes in tree_view. 


void gtk_tree_view_expand_to_path (GtkTreeView *tree_view, GtkTreePath xpath) 


Expands the row at path. 


gboolean gtk_tree_view_expand_row (GtkTreeView xtree_view, GtkTreePath xpath, gboolean 
open_all) 


Opens the row so its children are visible. 


gboolean gtk_tree_view_collapse_row (GtkTreeView *tree_view, GtkTreePath *path) 


Collapses a row (hides its child rows, if they exist). 


void gtk_tree_view_map_expanded_rows (GtkTreeView xtree_view, GtkTreeViewMappingFunc 
func, gpointer data) 


Calls func on all expanded rows. 


gboolean gtk_tree_view_row_expanded (GtkTree View *tree_view, GtkTreePath xpath) 


Returns TRUE if the node pointed to by path is expanded in tree_view. 


void gtk_tree_view_set_reorderable (GtkTreeView x*tree_view, gboolean reorderable) 


This function is a convenience function to allow you to reorder models that support the GtkDragSourcelface 
and the GtkDragDestlface. 


gboolean gtk_tree_view_get_reorderable (GtkTree View x*tree_view) 


Retrieves whether the user can reorder the tree via drag-and-drop. 


void gtk_tree_view_set_cursor (GtkTree View x*tree_view, GtkTreePath «path, GtkTree ViewColumn 
*focus_column, gboolean start_editing) 


Sets the current keyboard focus to be at path, and selects it. 


void gtk_tree_view_set_cursor_on_cell (GtkTreeView «*tree_view, GtkTreePath xpath, GtkTree- 
ViewColumn *focus_column, GtkCellRenderer *focus_cell, gboolean start_editing) 


Sets the current keyboard focus to be at path, and selects it. 


void gtk_tree_view_get_cursor (GtkTreeView *tree_view, GtkTreePath *xpath, GtkTree ViewCol- 
umn **focus_column) 


Fills in path and focus_column with the current path and focus column. 


GdkWindow * gtk_tree_view_get_bin_window (GtkTree View xtree_view) 


Returns the window that tree_view renders to. 
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e gboolean gtk_tree_view_get_path_at_pos (GtkTreeView x*tree_view, gint x, gint y, GtkTreePath 
*xpath, GtkTree ViewColumn **column, gint *cell_x, gint *cell_y) 


Finds the path at the point (x, y), relative to widget coordinates. 


e void gtk _tree_view_get_cell_area (GtkTreeView +tree_view, GtkTreePath «path, GtkTree ViewCol- 
umn «column, GdkRectangle rect) 


Fills the bounding rectangle in tree window coordinates for the cell at the row specified by path and the 
column specified by column. 


e void gtk_tree_view_get_background_area (GtkTree View x*tree_view, GtkTreePath xpath, GtkTree- 
ViewColumn «column, GdkRectangle xrect) 


Fills the bounding rectangle in tree window coordinates for the cell at the row specified by path and the 
column specified by column. 


e void gtk_tree_view_get_visible_rect (GtkTreeView x*tree_view, GdkRectangle *visible_rect) 


Fills visible_rect with the currently-visible region of the buffer, in tree coordinates. 


e void gtk _tree_view_widget_to_tree_coords (GtkTreeView x*tree_view, gint wx, gint wy, gint *tx, 
gint xty) 


Converts widget coordinates to coordinates for the tree window (the full scrollable area of the tree). 


e void gtk_tree_view_tree_to_widget_coords (GtkTree View *tree_view, gint tx, gint ty, gint xwx, gint 
*wy) 


Converts widget coordinates to coordinates for the tree window (the full scrollable area of the tree). 


e gboolean gtk_tree_view_get_visible_range (GtkTreeView »tree_view, GtkTreePath *xstart_path, 
GtkTreePath **end_path) 


Sets start_path and end_path to be the first and last visible path. 


e void gtk tree_view_enable_model_drag_source (GtkTreeView xtree_view, GdkModifierType 
start_button_mask, const GtkTargetEntry «targets, gint n_targets, GdkDragAction actions) 


[Deprecated] Turns tree_view into a drag source for automatic DND. 


e void gtk _tree_view_enable_model_drag_dest (GtkTreeView xtree_view, const GtkTargetEntry 
«targets, gint n_targets, GdkDragAction actions) 


[Deprecated] Turns tree_view into a drop destination for automatic DND. 


e void gtk_tree_view_unset_rows_drag_source (GtkTreeView *tree_view) 


[Deprecated] Undoes the effect of gtk_tree_view_enable_model_drag_dest(). 


e void gtk_tree_view_unset_rows_drag_dest (GtkTreeView *tree_view) 


[Deprecated] Undoes the effect of gtk_tree_view_enable_model_drag_source(). 


e void gtk_tree_view_set_drag_dest_row (GtkTreeView «*tree_view, GtkTreePath «path, GtkTree- 
ViewDropPosition pos) 


[Deprecated] Sets the row that is highlighted for feedback. 


e void gtk tree_view_get_drag_dest_row (GtkTreeView *tree_view, GtkTreePath *x*path, GtkTree- 
ViewDropPosition xpos) 


[Deprecated] Gets information about the row that is highlighted for feedback. 
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gboolean gtk_tree_view_get_dest_row_at_pos (GtkTree View *tree_view, gint drag_x, gint drag_y, 
GtkTreePath **path, GtkTreeViewDropPosition *pos) 


[Deprecated] Determines the destination row for a given position. 


GdkPixmap » gtk_tree_view_create_row_drag_icon (GtkTreeView xtree_view, GtkTreePath 
*path) 


[Deprecated] Creates a GdkPixmap representation of the row at path. 


void gtk_tree_view_set_enable_search (GtkTree View x*tree_view, gboolean enable_search) 


If enable_search is set, then the user can type in text to search through the tree interactively (this is some- 
times called "typeahead find"). 


gboolean gtk_tree_view_get_enable_search (GtkTreeView *tree_view) 


Returns whether or not the tree allows to start interactive searching by typing in text. 


gint gtk_tree_view_get_search_column (GtkTreeView *tree_view) 


Gets the column searched on by the interactive search code. 


void gtk_tree_view_set_search_column (GtkTreeView *tree_view, gint column) 


Sets column as the column where the interactive search code should search in. 


GtkTreeViewSearchEqualFunc gtk_tree_view_get_search_equal_func (GtkTreeView x*tree_view) 


Returns the compare function currently in use. 


void gtk_tree_view_set_search_equal_func (GtkTreeView xtree_view, GtkTreeViewSearchEqual- 
Func search_equal_func, gpointer search_user_data, GtkDestroyNotify search_destroy) 


Sets the compare function for the interactive search capabilities; note that somewhat like strcmp() returning 
0 for equality GtkTree ViewSearchEqualFunc returns FALSE on matches. 


GtkEntry x gtk_tree_view_get_search_entry (GtkTreeView *tree_view) 


Returns the GtkEntry which is currently in use as interactive search entry for tree_view. 


void gtk_tree_view_set_search_entry (GtkTree View *tree_view, GtkEntry *entry) 


Sets the entry which the interactive search code will use for this tree_view. 


GtkTreeViewSearchPositionFunc gtk_tree_view_get_search_position_func (GtkTreeView xtree_- 
view) 


Returns the positioning function currently in use. 


void gtk_tree_view_set_search_position_func (GtkTreeView xtree_view, GtkTreeViewSearchPosi- 
tionFunc func, gpointer data, GDestroyNotify destroy) 


Sets the function to use when positioning the seach dialog. 


void gtk_tree_view_set_destroy_count_func (GtkTreeView *tree_view, GtkTreeDestroyCountFunc 
func, gpointer data, GtkDestroyNotify destroy) 


It is meant for private use by ATK for determining the number of visible children that are removed when the 
user collapses a row, or a row is deleted. 


void gtk_tree_view_set_fixed_height_mode (GtkTreeView *tree_view, gboolean enable) 


Enables or disables the fixed height mode of tree_view. 
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e gboolean gtk_tree_view_get_fixed_height_mode (GtkTree View *tree_view) 


Returns whether fixed height mode is turned on for tree_view. 


e void gtk_tree_view_set_hover_selection (GtkTree View *tree_view, gboolean hover) 


Enables of disables the hover selection mode of tree_view. 


e gboolean gtk_tree_view_get_hover_selection (GtkTreeView +*tree_view) 


Returns whether hover selection mode is turned on for tree_view. 


e void gtk_tree_view_set_hover_expand (GtkTreeView *tree_view, gboolean expand) 


Enables of disables the hover expansion mode of tree_view. 


e gboolean gtk_tree_view_get_hover_expand (GtkTreeView x*tree_view) 


Returns whether hover expansion mode is turned on for tree_view. 


e void gtk_tree_view_set_rubber_banding (GtkTree View x*tree_view, gboolean enable) 


Enables or disables rubber banding in tree_view. 


e gboolean gtk_tree_view_get_rubber_banding (GtkTreeView *tree_view) 


Returns whether rubber banding is turned on for tree_view. 


e GtkTreeViewRowSeparatorFunc gtk_tree_view_get_row_separator_func (GtkTreeView xtree_- 
view) 


Returns the current row separator function. 


e void gtk_tree_view_set_row_separator_func (GtkTreeView xtree_view, GtkTreeViewRowSepara- 
torFunc func, gpointer data, GtkDestroyNotify destroy) 


Sets the row separator function, which is used to determine whether a row should be drawn as a separator. 


e GtkTreeViewGridLines gtk_tree_view_get_grid_lines (GtkTreeView x*tree_view) 


Returns which grid lines are enabled in tree_view. 


e void gtk_tree_view_set_grid_lines (GtkTree View xtree_view, GtkTreeViewGridLines grid_lines) 


Sets which grid lines to draw in tree_view. 


e gboolean gtk_tree_view_get_enable_tree_lines (GtkTreeView *tree_view) 


Returns whether or not tree lines are drawn in tree_view. 


e void gtk_tree_view_set_enable_tree_lines (GtkTreeView x*tree_view, gboolean enabled) 


Sets whether to draw lines interconnecting the expanders in tree_view. 


e gboolean gtk_tree_view_clear_all_item (GtkTree View *tree_view) 


Delete all items with their data. 


e gint gtk_tree_view_set_tree_zoom_flag (GtkTree View *tree_view, gboolean flag) 


Set treeview zoom flag. 


e gint gtk_tree_view_set_zoom_line_height (GtkTreeView *tree_view, guint height) 


Sets treeview zoom line height. 
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6.52.2 Typedef Documentation 


6.52.2.1 typedef void(« GtkTreeDestroyCountFunc)(GtkTreeView xtree_view, GtkTreePath «path, 
gint children, gpointer user_data) 


destroys the tree view count function 


Parameters: 


tree_view [in] A GtkTreeView 
path [in] The path that's expanded 
children [in] index of the child 


user_data [in] user data 


Returns: 


void 


6.52.2.2 typedef gboolean(* GtkTreeViewColumnDropFunc)(GtkTreeView xtree_view, 
GtkTreeViewColumn «column, GtkTree ViewColumn «prev_column, 
GtkTreeViewColumn *next_column, gpointer data) 


Function type for determining whether column can be dropped in a particular spot (as determined by prev_- 
column and next_column). 


In left to right locales, prev_column is on the left of the potential drop spot, and next_column is on the 
right. In right to left mode, this is reversed. This function should return TRUE if the spot is a valid drop 
spot. Please note that returning TRUE does not actually indicate that the column drop was made, but is 
meant only to indicate a possible drop spot to the user. 
Parameters: 

tree_view [in] A GtkTreeView 

column [in] The GtkTreeViewColumn being dragged 

prev_column [in] A GtkTreeViewColumn on one side of column 

next_column [in] A GtkTreeViewColumn on the other side of column 


data [in] user data 


Returns: 


void TRUE, if column can be dropped in this spot 


6.52.2.3 typedef void(« GtkTreeViewMappingFunc)(GtkTreeView «tree_view, GtkTreePath «path, 
gpointer user_data) 


Function used for gtk_tree_view_map_expanded_rows. 


Parameters: 


tree_view [in] A GtkTreeView 


path [in] The path that’s expanded 
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user_data [in] user data 


Returns: 


void 


6.52.2.4 typedef gboolean(« GtkTree ViewRowSeparatorFunc)(GtkTreeModel «model, 
GtkTreelter xiter, gpointer data) 
Function type for determining whether the row pointed to by iter should be rendered as a separator. 


A common way to implement this is to have a boolean column in the model, whose values the GtkTree- 
ViewRowSeparatorFunc returns. 


Parameters: 


model [in] the GtkTreeModel 
iter [in] a GtkTreelter pointing at a row in model 


data [in] user data 


Returns: 


TRUE if the row is a separator 


6.52.2.5 typedef gboolean(« GtkTreeViewSearchEqualFunc)(GtkTreeModel «model, gint column, 
const gchar «key, GtkTreelter xiter, gpointer search_data) 

A function used for checking whether a row in model matches a search key string entered by the user. 

Note the return value is reversed from what you would normally expect, though it has some similarity to 

stremp() returning O for equal strings. 

Parameters: 


model [in] the GtkTreeModel 


column [in] the search column set by gtk_tree_view_set_search_column() 


key [in] the key string to compare with 
iter [in] a GtkTreelter pointing the row of model that should be compared with key. 


search_data [in] user data from gtk_tree_view_set_search_equal_func() 


Returns: 


FALSE if the row matches, TRUE otherwise. 


6.52.2.6 typedef void(« GtkTree ViewSearchPositionFunc)(GtkTreeView «tree_view, Gtk Widget 
*search_dialog, gpointer user_data) 


Function used to Tree View Position Func. 


Parameters: 


tree_view [in] A GtkTreeView 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


524 Module Documentation 


search_dialog [in] a dialog widget 


user_data [in] user data 
Returns: 
void 
6.52.3 Function Documentation 


6.52.3.1 gint gtk_tree_view_append_column (GtkTreeView x tree_view, GtkTreeViewColumn x 
column) 


Appends column to the list of columns. 

If tree_view has "fixed_height" mode enabled, then column must have its "sizing" property set to be GTK_- 
TREE_VIEW_COLUMN_FIXED. 

Parameters: 


tree_view [in] A GtkTreeView 


column [in] The GtkTreeViewColumn to add. 


Returns: 


The number of columns in tree_view after appending. 


6.52.3.2 gboolean gtk_tree_view_clear_all_item (GtkTreeView + tree_view) 


Delete all items with their data. 


Parameters: 


tree_view [in] A GtkTreeView. 


Returns: 


TRUE if suceed, FALSE if not. 


Since 


LIMO RI 


6.52.3.3 void gtk_tree_view_collapse_all (GtkTreeView x tree_view) 
Recursively collapses all visible, expanded nodes in tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


void 
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6.52.3.4 gboolean gtk_tree_view_collapse_row (GtkTreeView « tree_view, GtkTreePath + path) 


Collapses a row (hides its child rows, if they exist). 


Parameters: 
tree_view [in] A GtkTreeView 


path [in] path to a row in the tree_view 


Returns: 


TRUE if the row was collapsed. 


6.52.3.5 void gtk_tree_view_columns_autosize (GtkTreeView x tree_view) 


Resizes all columns to their optimal width. 


Only works after the treeview has been realized. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


void 


6.52.3.6 GdkPixmapx gtk_tree_view_create_row_drag_icon (GtkTreeView * tree_view, 
GtkTreePath x path) 


[Deprecated] Creates a GdkPixmap representation of the row at path. 


This image is used for a drag icon. 


Parameters: 
tree_view [in] A GtkTreeView 


path [in] a GtkTreePath in tree_view 


Returns: 


a newly-allocated pixmap of the drag icon. 


Deprecated 
LIMO R1 


6.52.3.7 void gtk_tree_view_enable_model_drag_dest (GtkTreeView x tree_view, const 
GtkTargetEntry + targets, gint n_targets, GdkDragAction actions) 


[Deprecated] Turns tree_view into a drop destination for automatic DND. 
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Parameters: 
tree_view [in] A GtkTreeView 
start_button_mask [in] Mask of allowed buttons to start drag 
targets [in] the table of targets that the drag will support 
n_targets [in] the number of items in targets 


actions [in] the bitmask of possible actions for a drag from this widget 
Returns: 
void 


Deprecated 
LIMO R1 


6.52.3.8 void gtk_tree_view_enable_model_drag_source (GtkTreeView + tree_view, 
GdkModifierType start_button_mask, const GtkTargetEntry * targets, gint n_targets, 
GdkDragAction actions) 


[Deprecated] Turns tree_view into a drag source for automatic DND. 


Parameters: 
tree_view [in] A GtkTreeView 
start_button_mask [in] Mask of allowed buttons to start drag 
targets [in] the table of targets that the drag will support 
n_targets [in] the number of items in targets 


actions [in] the bitmask of possible actions for a drag from this widget 


Returns: 


void 


Deprecated 
LIMO R1 


6.52.3.9 void gtk_tree_view_expand_all (GtkTreeView x tree_view) 


Recursively expands all nodes in the tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


void 
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6.52.3.10 gboolean gtk_tree_view_expand_row (GtkTreeView « tree_view, GtkTreePath x path, 
gboolean open_all) 


Opens the row so its children are visible. 


Parameters: 


tree_view [in] A GtkTreeView 
path [in] path to a row 


open_all [in] whether to recursively expand, or just expand immediate children 


Returns: 


TRUE if the row existed and had children 


6.52.3.11 void gtk_tree_view_expand_to_path (GtkTreeView x tree_view, GtkTreePath + path) 


Expands the row at path. 


This will also expand all parent rows of path as necessary. 


Parameters: 


tree_view [in] A GtkTreeView 


path [in] path to a row. 


Returns: 


void 


6.52.3.12 void gtk_tree_view_get_background_area (GtkTreeView x tree_view, GtkTreePath + 
path, GtkTreeViewColumn * column, GdkRectangle « rect) 


Fills the bounding rectangle in tree window coordinates for the cell at the row specified by path and the 
column specified by column. 


If path is NULL, or points to a node not found in the tree, the y and height fields of the rectangle will 
be filled with 0. If column is NULL, the x and width fields will be filled with 0. The returned rectangle 
1s equivalent to the background_area passed to gtk_cell_renderer_render(). These background areas tile 
to cover the entire tree window (except for the area used for header buttons). Contrast with the cell_- 
area, returned by gtk_tree_view_get_cell_area(), which returns only the cell itself, excluding surrounding 
borders and the tree expander area. 


Parameters: 


tree_view [in] A GtkTreeView 
path [in] a GtkTreePath for the row, or NULL to get only horizontal coordinates 
column [in] a GtkTreeViewColumn for the column, or NULL to get only vertical coordiantes 


rect [in] rectangle to fill with cell background rect 


Returns: 


void 
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6.52.3.13 GdkWindowx gtk_tree_view_get_bin_window (GtkTree View + tree_view) 


Returns the window that tree_view renders to. 

This is used primarily to compare to event-> window to confirm that the event on tree_view is on the right 
window. 

Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


A GdkWindow, or NULL when tree_view hasn't been realized yet 


6.52.3.14 void gtk_tree_view_get_cell_area (GtkTreeView + tree_view, GtkTreePath x path, 
GtkTreeViewColumn * column, GdkRectangle + rect) 


Fills the bounding rectangle in tree window coordinates for the cell at the row specified by path and the 
column specified by column. 


If path is NULL, or points to a path not currently displayed, the y and height fields of the rectangle will 
be filled with 0. If column is NULL, the x and width fields will be filled with 0. The sum of all cell rects 
does not cover the entire tree; there are extra pixels in between rows, for example. The returned rectangle 
is equivalent to the cell_area passed to gtk_cell_renderer_render(). This function is only valid if tree_view 
is realized. 
Parameters: 

tree_view [in] A GtkTreeView 

path [in] a GtkTreePath for the row, or NULL to get only horizontal coordinates 


column [in] a GtkTreeViewColumn for the column, or NULL to get only vertical coordinates 


rect [in] rectangle to fill with cell rect 


Returns: 


void 


6.52.3.15 GtkTreeViewColumn* gtk_tree_view_get_column (GtkTreeView x tree_view, gint n) 


Gets the GtkTree ViewColumn at the given position in the tree_view. 


Parameters: 
tree_view [in] A GtkTreeView 


n [in] The position of the column, counting from 0. 


Returns: 


The GtkTreeViewColumn, or NULL if the position is outside the range of columns. 
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6.52.3.16 GList« gtk_tree_view_get_columns (GtkTreeView + tree_view) 


Returns a GList of all the GtkTree ViewColumn s currently in tree_view. 


The returned list must be freed with g_list_free(). 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


A list of GtkTree ViewColumn s 


6.52.3.17 void gtk_tree_view_get_cursor (GtkTreeView x tree_view, GtkTreePath xx path, 
GtkTreeViewColumn «* focus_column) 
Fills in path and focus_column with the current path and focus column. 


If the cursor isn’t currently set, then «path will be NULL. If no column currently has focus, then *focus_- 
column will be NULL. 


The returned GtkTreePath must be freed with gtk_tree_path_free() when you are done with it. 
Parameters: 

tree_view [in] A GtkTreeView 

path [out] A pointer to be filled with the current cursor path, or NULL 

focus_column [out] A pointer to be filled with the current cursor path, or NULL 
Returns: 

void 
Remarks: 


The returned GtkTreePath must be freed with gtk_tree_path_free() when you are done with it. 


6.52.3.18 gboolean gtk_tree_view_get_dest_row_at_pos (GtkTreeView x tree_view, gint drag_x, 
gint drag_y, GtkTreePath «* path, GtkTreeViewDropPosition x pos) 


[Deprecated] Determines the destination row for a given position. 


Parameters: 


tree_view [in] A GtkTreeView 

drag_x [in] the position to determine the destination row for 

drag_y [in] the position to determine the destination row for 

path [out] Return location for the path of the highlighted row, or NULL. 
pos [out] Return location for the drop position, or NULL 


Returns: 


whether there is a row at the given position. 
Deprecated 
LIMO RI 
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6.52.3.19 void gtk_tree_view_get_drag_dest_row (GtkTreeView « tree_view, GtkTreePath «+ path, 
GtkTreeViewDropPosition x pos) 


[Deprecated] Gets information about the row that is highlighted for feedback. 


Parameters: 


tree_view [in] A GtkTreeView 
path [out] Return location for the path of the highlighted row, or NULL. 
pos [out] Return location for the drop position, or NULL 


Returns: 
void 
Deprecated 
LIMO R1 


6.52.3.20 gboolean gtk_tree_view_get_enable_search (GtkTreeView * tree_view) 


Returns whether or not the tree allows to start interactive searching by typing in text. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


whether or not to let the user search interactively 


6.52.3.21 gboolean gtk_tree_view_get_enable_tree_lines (GtkTree View + tree_view) 


Returns whether or not tree lines are drawn in tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if tree lines are drawn in tree_view, FALSE otherwise. 


6.52.3.22 GtkTreeViewColumn~« gtk_tree_view_get_expander_column (GtkTreeView x tree_view) 
Returns the column that is the current expander column. 
This column has the expander arrow drawn next to it. 
Parameters: 
tree_view [in] A GtkTreeView 


Returns: 


The expander column. 
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6.52.3.23 gboolean gtk_tree_view_get_fixed_height_mode (GtkTreeView « tree_view) 


Returns whether fixed height mode is turned on for tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if tree_view is in fixed height mode 


6.52.3.24 GtkTreeViewGridLines gtk_tree_view_get_grid_lines (GtkTree View x tree_view) 


Returns which grid lines are enabled in tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


a GtkTreeViewGridLines value indicating which grid lines are enabled. 


6.52.3.25  GtkAdjustmentx gtk_tree_view_get_hadjustment (GtkTreeView x tree_view) 


Gets the GtkAdjustment currently being used for the horizontal aspect. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


A GtkAdjustment object, or NULL if none is currently being used. 


6.52.3.26 gboolean gtk_tree_view_get_headers_clickable (GtkTree View x tree_view) 


[Deprecated] Returns whether all header columns are clickable. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if all header columns are clickable, otherwise FALSE 


Deprecated 
LIMO R1 
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6.52.3.27 gboolean gtk_tree_view_get_headers_visible (GtkTreeView + tree_view) 


Returns TRUE if the headers on the tree_view are visible. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


Whether the headers are visible or not. 


6.52.3.28 gboolean gtk_tree_view_get_hover_expand (GtkTreeView x tree_view) 


Returns whether hover expansion mode is turned on for tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if tree_view is in hover expansion mode 


6.52.3.29 gboolean gtk_tree_view_get_hover_selection (GtkTreeView x tree_view) 


Returns whether hover selection mode is turned on for tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if tree_view is in hover selection mode 


6.52.3.30 GtkTreeModel« gtk_tree_view_get_model (GtkTree View x tree_view) 


Returns the model the GtkTree View is based on. 


Returns NULL if the model is unset. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


A GtkTreeModel, or NULL if none is currently being used. 
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6.52.3.31 gboolean gtk_tree_view_get_path_at_pos (GtkTreeView « tree_view, gint x, gint y, 
GtkTreePath xx path, GtkTreeViewColumn xx column, gint x cell_x, gint x cell_y) 


Finds the path at the point (x, y), relative to widget coordinates. 


That is, x and y are relative to an events coordinates. x and y must come from an event on the tree_view 
only where event->window == gtk_tree_view_get_bin (). It is primarily for things like popup menus. If 
path is non-NULL, then it will be filled with the GtkTreePath at that point. This path should be freed 
with gtk_tree_path_free(). If column is non-NULL, then it will be filled with the column at that point. 
cell_x and cell_y return the coordinates relative to the cell background (i.e. the background_area passed to 
gtk_cell_renderer_render()). This function is only meaningful if tree_view is realized. 
Parameters: 

tree_view [in] A GtkTreeView 

x [in] The x position to be identified. 

y [in] The y position to be identified. 

path [out] A pointer to a GtkTreePath pointer to be filled in, or NULL 

column [out] A pointer to a GtkTreeViewColumn pointer to be filled in, or NULL 

cell_x [out] A pointer where the X coordinate relative to the cell can be placed, or NULL 


cell_y [out] A pointer where the Y coordinate relative to the cell can be placed, or NULL 


Returns: 


TRUE if a row exists at that coordinate. 


6.52.3.32 gboolean gtk_tree_view_get_reorderable (GtkTree View « tree_view) 


Retrieves whether the user can reorder the tree via drag-and-drop. 


See gtk_tree_view_set_reorderable(). 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if the tree can be reordered. 


6.52.3.33 GtkTreeViewRowSeparatorFunc gtk_tree_view_get_row_separator_func (GtkTree View 
x tree_view) 


Returns the current row separator function. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


the current row separator function. 
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6.52.3.34 gboolean gtk_tree_view_get_rubber_banding (GtkTreeView + tree_view) 


Returns whether rubber banding is turned on for tree_view. 

If the selection mode is GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select 
multiple rows by dragging the mouse. 

Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if rubber banding in tree_view is enabled. 


6.52.3.35 gboolean gtk_tree_view_get_rules_hint (GtkTreeView x tree_view) 


Gets the setting set by gtk_tree_view_set_rules_hint(). 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


TRUE if rules are useful for the user of this tree 


6.52.3.36 gint gtk_tree_view_get_search_column (GtkTreeView + tree_view) 


Gets the column searched on by the interactive search code. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


the column the interactive search code searches in. 


6.52.3.37 GtkEntryx gtk_tree_view_get_search_entry (GtkTreeView + tree_view) 


Returns the GtkEntry which is currently in use as interactive search entry for tree_view. 


In case the built-in entry is being used, NULL will be returned. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


the entry currently in use as search entry. 
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6.52.3.38 GtkTreeViewSearchEqualFunc gtk_tree_view_get_search_equal_func (GtkTree View + 
tree_view) 


Returns the compare function currently in use. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


the currently used compare function for the search code. 


6.52.3.39 GtkTreeViewSearchPositionFunc gtk_tree_view_get_search_position_func 
(GtkTree View x tree_view) 


Returns the positioning function currently in use. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


the currently used function for positioning the search dialog. 


6.52.3.40 GtkTreeSelection« gtk_tree_view_get_selection (GtkTreeView x tree_view) 
Gets the GtkTreeSelection associated with tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


A GtkTreeSelection object. 


6.52.3.41 GtkAdjustmentx gtk_tree_view_get_vadjustment (GtkTreeView x tree_view) 


Gets the GtkAdjustment currently being used for the vertical aspect. 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


A GtkAdjustment object, or NULL if none is currently being used. 
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6.52.3.42  gboolean gtk_tree_view_get_visible_range (GtkTreeView « tree_view, GtkTreePath xx 
start_path, GtkTreePath xx end_path) 


Sets start_path and end_path to be the first and last visible path. 
Note that there may be invisible paths in between. 


The paths should be freed with gtk_tree_path_free() after use. 


Parameters: 
tree_view [in] A GtkTreeView 
start_path [out] Return location for start of region, or NULL. 
end_path [out] Return location for end of region, or NULL. 
Returns: 


TRUE, if valid paths were placed in start_path and end_path. 


Remarks: 


The paths should be freed with gtk_tree_path_free() after use. 


6.52.3.43 void gtk_tree_view_get_visible_rect (GtkTreeView x tree_view, GdkRectangle x 
visible_rect) 


Fills visible_rect with the currently-visible region of the buffer, in tree coordinates. 


Convert to widget coordinates with gtk_tree_view_tree_to_widget_coords(). Tree coordinates start at 0,0 
for row 0 of the tree, and cover the entire scrollable area of the tree. 


Parameters: 
tree_view [in] A GtkTreeView 
visible_rect [in] rectangle to fill 
Returns: 


void 


6.52.3.44 gint gtk_tree_view_insert_column (GtkTreeView x tree_view, GtkTreeViewColumn = 
column, gint position) 


This inserts the column into the tree_view at position. 


If position is -1, then the column is inserted at the end. If tree_view has "fixed_height" mode enabled, then 
column must have its "sizing" property set to be GTK_TREE_VIEW_COLUMN_FIXED. 


Parameters: 
tree_view [in] A GtkTreeView 
column [in] The GtkTree ViewColumn to be inserted. 
position [in] he position to insert column in. 
Returns: 


The number of columns in tree_view after insertion. 
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6.52.3.45 gint gtk_tree_view_insert_column_with_attributes (GtkTreeView « tree_view, gint 
position, const gchar x title, GtkCellRenderer x cell, ...) 


Creates a new GtkTree ViewColumn and inserts it into the tree_view at position. 


If position is -1, then the newly created column is inserted at the end. The column is initialized with the 
attributes given. If tree_view has "fixed_height" mode enabled, then the new column will have its sizing 
property set to be GTK_TREE_VIEW_COLUMN_FIXED. 


Parameters: 


tree_view [in] A GtkTreeView 

position [in] The position to insert the new column in. 
title [in] The GtkCellRenderer. 

cell [in] cell renderer for column 


. [in] A NULL-terminated list of attributes. 


Returns: 


The number of columns in tree_view after insertion. 


6.52.3.46 gint gtk_tree_view_insert_column_with_data_func (GtkTreeView x tree_view, gint 
position, const gchar + title, GtkCellRenderer x cell, GtkTreeCellDataFunc func, 
gpointer data, GDestroyNotify dnotify) 


Convenience function that inserts a new column into the GtkTreeView with the given cell renderer and a 
GtkCellDataFunc to set cell renderer attributes (normally using data from the model). 


See also gtk_tree_view_column_set_cell_data_func(), gtk_tree_view_column_pack_start(). If tree_view 
has "fixed_height" mode enabled, then the new column will have its "sizing" property set to be GTK_- 
TREE_VIEW_COLUMN_FIXED. 


Parameters: 
tree_view [in] A GtkTreeView 
position [in] Position to insert, -1 for append 
title [in] column title 
cell [in] cell renderer for column 
func [in] function to set attributes of cell renderer 
data [in] data for func 


dnotify [in] destroy notifier for data 


Returns: 


number of columns in the tree view post-insert 


6.52.3.47 void gtk_tree_view_map_expanded_rows (GtkTreeView x tree_view, 
GtkTreeViewMappingFunc func, gpointer data) 


Calls func on all expanded rows. 
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Parameters: 
tree_view [in] A GtkTreeView 
func [in] A function to be called 


data [in] User data to be passed to the function. 


Returns: 


void 


6.52.3.48 void gtk_tree_view_move_column_after (GtkTreeView + tree_view, GtkTree ViewColumn 
x column, GtkTreeViewColumn x base_column) 


Moves column to be after to base_column. 


If base_column is NULL, then column is placed in the first position. 


Parameters: 
tree_view [in] A GtkTreeView 
column [in] The GtkTreeViewColumn to be moved. 


base_column [in] The GtkTreeViewColumn to be moved relative to, or NULL. 


Returns: 


void 


6.52.3.49 GtkWidgetx gtk_tree_view_new (void) 


Creates a new GtkTree View widget. 


Returns: 


A newly created GtkTree View widget. 


6.52.3.50 GtkWidget» gtk_tree_view_new_with_model (GtkTreeModel « model) 


Creates a new GtkTree View widget with the model initialized to model. 


Parameters: 


model [in] the model. 


Returns: 


A newly created GtkTree View widget. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.52 GtkTreeview 539 


6.52.3.51 gint gtk_tree_view_remove_column (GtkTreeView x tree_view, GtkTreeViewColumn + 
column) 


Removes column from tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


column [in] The GtkTreeViewColumn to remove. 


Returns: 


The number of columns in tree_view after removing. 


6.52.3.52 void gtk_tree_view_row_activated (GtkTreeView x tree_view, GtkTreePath x path, 
GtkTreeViewColumn * column) 


Activates the cell determined by path and column. 


Parameters: 


tree_view [in] A GtkTreeView 
path The GtkTreePath to be activated. 


column The GtkTreeViewColumn to be activated. 


Returns: 


void 


6.52.3.53 gboolean gtk_tree_view_row_expanded (GtkTreeView + tree_view, GtkTreePath x path) 


Returns TRUE if the node pointed to by path is expanded in tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


path [in] A GtkTreePath to test expansion state. 


Returns: 


TRUE if path is expanded. 


6.52.3.54 void gtk_tree_view_scroll_to_cell (GtkTreeView + tree_view, GtkTreePath « path, 
GtkTreeViewColumn * column, gboolean use_align, gfloat row_align, gfloat col_align) 


Moves the alignments of tree_view to the position specified by column and path. 


If column is NULL, then no horizontal scrolling occurs. Likewise, if path is NULL no vertical scrolling 
occurs. At a minimum, one of column or path need to be non-NULL. row_align determines where the row 
is placed, and col_align determines where column is placed. Both are expected to be between 0.0 and 1.0. 
0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. 
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If use_align is FALSE, then the alignment arguments are ignored, and the tree does the minimum amount 
of work to scroll the cell onto the screen. This means that the cell will be scrolled to the edge closest to its 
current position. If the cell is currently visible on the screen, nothing is done. 


This function only works if the model is set, and path is a valid row on the model. If the model changes 
before the tree_view is realized, the centered path will be modified to reflect this change. 
Parameters: 


tree_view [in] A GtkTreeView 

path [in] The path of the row to move to, or NULL. 

column [in] The GtkTreeViewColumn to move horizontally to, or NULL. 
use_align [in] whether to use alignment arguments, or FALSE. 
row_align [in] The vertical alignment of the row specified by path. 


col_align [in] The horizontal alignment of the column specified by column. 


Returns: 


void 


6.52.3.55 void gtk_tree_view_scroll_to_point (GtkTreeView « tree_view, gint tree_x, gint tree_y) 


Scrolls the tree view such that the top-left corner of the visible area is tree_x, tree_y, where tree_x and 
tree_y are specified in tree window coordinates. 


The tree_view must be realized before this function is called. If it isn’t, you probably want to be using 
gtk_tree_view_scroll_to_cell(). 


If either tree_x or tree_y are -1, then that direction isn’t scrolled. 


Parameters: 
tree_view [in] A GtkTreeView 
tree_x [in] X coordinate of new top-left pixel of visible area, or -1 
tree_y [in] Y coordinate of new top-left pixel of visible area, or -1 
Returns: 
void 
Remarks: 


If either tree_x or tree_y are -1, then that direction isn’t scrolled. 


6.52.3.56 void gtk_tree_view_set_column_drag_function (GtkTreeView x tree_view, 
GtkTreeViewColumnDropFunc func, gpointer user_data, GtkDestroyNotify destroy) 


[Deprecated] Sets a user function for determining where a column may be dropped when dragged.This 
function is called on every column pair in turn at the beginning of a column drag to determine where a drop 
can take place. 


The arguments passed to func are: the tree_view, the GtkTree ViewColumn being dragged, the two GtkTree- 
ViewColumn s determining the drop spot, and user_data. If either of the GtkTree ViewColumn arguments 
for the drop spot are NULL, then they indicate an edge. If func is set to be NULL, then tree_view reverts 
to the default behavior of allowing all columns to be dropped everywhere. 
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Parameters: 


tree_view [in] A GtkTreeView 

func [in] A function to determine which columns are reorderable, or NULL. 
user_data [in] User data to be passed to func, or NULL 

destroy [in] Destroy notifier for user_data, or NULL 


Returns: 


void 
Deprecated 
LIMO R1 


6.52.3.57 void gtk_tree_view_set_cursor (GtkTreeView « tree_view, GtkTreePath « path, 
GtkTreeViewColumn * focus_column, gboolean start_editing) 


Sets the current keyboard focus to be at path, and selects it. 


This is useful when you want to focus the user’s attention on a particular row. If focus_column is not 
NULL, then focus is given to the column specified by it. Additionally, if focus_column is specified, and 
start_editing is TRUE, then editing should be started in the specified cell. This function is often followed by 
gtk_widget_grab_focus (tree_view) in order to give keyboard focus to the widget. Please note that editing 
can only happen when the widget is realized. 


Parameters: 


tree_view [in] A GtkTreeView 

path [in] A GtkTreePath 

focus_column [in] A GtkTreeViewColumn, or NULL 

start_editing [in] TRUE if the specified cell should start being edited. 


Returns: 


void 


6.52.3.58 void gtk_tree_view_set_cursor_on_cell (GtkTreeView « tree_view, GtkTreePath + 
path, GtkTreeViewColumn x focus_column, GtkCellRenderer x focus_cell, gboolean 
start_editing) 


Sets the current keyboard focus to be at path, and selects it. 


This is useful when you want to focus the user's attention on a particular row. If focus_column is not 
NULL, then focus is given to the column specified by it. If focus_column and focus_cell are not NULL, 
and focus_column contains 2 or more editable or activatable cells, then focus is given to the cell specified 
by focus_cell. Additionally, if focus_column is specified, and start_editing is TRUE, then editing should 
be started in the specified cell. This function is often followed by gtk_widget_grab_focus (tree_view) in 
order to give keyboard focus to the widget. Please note that editing can only happen when the widget is 
realized. 


Parameters: 


tree_view [in] A GtkTreeView 
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path [in] A GtkTreePath 

focus_column [in] A GtkTreeView 

focus_cell [in] A GtkTreeViewColumn, or NULL 

start_editing [in] TRUE if the specified cell should start being edited 


Returns: 


void 


6.52.3.59 void gtk_tree_view_set_destroy_count_func (GtkTreeView + tree_view, 
GtkTreeDestroyCountFunc func, gpointer data, GtkDestroyNotify destroy) 


It is meant for private use by ATK for determining the number of visible children that are removed when 
the user collapses a row, or a row is deleted. 


Parameters: 
tree_view [in] A GtkTreeView 
func [in] Function to be called when a view row is destroyed, or NULL 
data [in] User data to be passed to func, or NULL 
destroy [in] Destroy notifier for data, or NULL 


Returns: 


void 


6.52.3.60 void gtk_tree_view_set_drag_dest_row (GtkTreeView « tree_view, GtkTreePath + path, 
GtkTreeViewDropPosition pos) 


[Deprecated] Sets the row that is highlighted for feedback. 


Parameters: 
tree_view [in] A GtkTreeView 
path [in] The path of the row to highlight, or NULL. 


pos [in] Specifies whether to drop before, after or into the row 


Returns: 


void 


Deprecated 
LIMO R1 
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6.52.3.61 void gtk_tree_view_set_enable_search (GtkTreeView + tree_view, gboolean 
enable_search) 


If enable_search is set, then the user can type in text to search through the tree interactively (this is some- 
times called "typeahead find"). 


Note that even if this is FALSE, the user can still initiate a search using the "start-interactive-search" key 
binding. 
Parameters: 


tree_view [in] A GtkTreeView 


enable_search [in] TRUE, if the user can search interactively 


Returns: 


void 


Note: 


even if enable_search is FALSE, the user can still initiate a search using the "start-interactive-search" 
key binding. 


6.52.3.62 void gtk_tree_view_set_enable_tree_lines (GtkTreeView + tree_view, gboolean enabled) 


Sets whether to draw lines interconnecting the expanders in tree_view. 


This does not have any visible effects for lists. 


Parameters: 


tree_view [in] A GtkTreeView 
enabled [in] TRUE to enable tree line drawing, FALSE otherwise. 


Returns: 


void 


6.52.3.63 void gtk_tree_view_set_expander_column (GtkTreeView « tree_view, 
GtkTreeViewColumn * column) 

Sets the column to draw the expander arrow at. 

It must be in tree_view. If column is NULL, then the expander arrow is always at the first visible column. 


If you do not want expander arrow to appear in your tree, set the expander column to a hidden column. 


Parameters: 


tree_view [in] A GtkTreeView 


column [in] NULL, or the column to draw the expander arrow at. 


Returns: 


void 
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6.52.3.64 void gtk_tree_view_set_fixed_height_mode (GtkTreeView x tree_view, gboolean enable) 


Enables or disables the fixed height mode of tree_view. 


Fixed height mode speeds up GtkTreeView by assuming that all rows have the same height. Only enable 
this option if all rows are the same height and all columns are of type GTK_TREE_VIEW_COLUMN_- 
FIXED. 


Parameters: 


tree_view [in] A GtkTreeView 
enable [in] TRUE to enable fixed height mode 


Returns: 


void 


6.52.3.65 void gtk_tree_view_set_grid_lines (GtkTreeView « tree_view, GtkTreeViewGridLines 
grid_lines) 


Sets which grid lines to draw in tree_view. 


Parameters: 


tree_view [in] A GtkTreeView 


grid_lines [in] a GtkTreeViewGridLines value indicating which grid lines to enable. 


Returns: 


void 


6.52.3.66 void gtk_tree_view_set_hadjustment (GtkTreeView + tree_view, GtkAdjustment + 
adjustment) 


Sets the GtkAdjustment for the current horizontal aspect. 


Parameters: 


tree_view [in] A GtkTreeView 
adjustment The GtkAdjustment to set, or NULL 


Returns: 


void 


6.52.3.67 void gtk_tree_view_set_headers_clickable (GtkTreeView « tree_view, gboolean setting) 


[Deprecated] Allow the column title buttons to be clicked. 


Parameters: 


tree_view [in] A GtkTreeView 
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setting [in] TRUE if the columns are clickable. 


Returns: 
void 
Deprecated 
LIMO R1 


6.52.3.68 void gtk_tree_view_set_headers_visible (GtkTreeView + tree_view, gboolean 
headers_visible) 


Sets the visibility state of the headers. 


Parameters: 


tree_view [in] A GtkTreeView 
headers_visible TRUE if the headers are visible 


Returns: 


void 


6.52.3.69 void gtk_tree_view_set_hover_expand (GtkTreeView * tree_view, gboolean expand) 


Enables of disables the hover expansion mode of tree_view. 


Hover expansion makes rows expand or collaps if the pointer moves over them. 


Parameters: 


tree_view [in] A GtkTreeView 


expand [in] TRUE to enable hover selection mode 


Returns: 


void 


6.52.3.70 void gtk_tree_view_set_hover_selection (GtkTreeView x tree_view, gboolean hover) 


Enables of disables the hover selection mode of tree_view. 


Hover selection makes the selected row follow the pointer. Currently, this works only for the selection 


modes GTK_SELECTION_SINGLE and GTK_SELECTION_BROWSE. 


Parameters: 


tree_view [in] A GtkTreeView 


hover [in] TRUE to enable hover selection mode 


Returns: 


void 
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6.52.3.71 void gtk_tree_view_set_model (GtkTreeView x tree_view, GtkTreeModel * model) 


Sets the model for a GtkTree View. 


If the tree_view already has a model set, it will remove it before setting the new model. If model is NULL, 
then it will unset the old model. 


Parameters: 


tree_view [in] A GtkTreeView 


model [in] the model. 


Returns: 


void 


6.52.3.72 void gtk_tree_view_set_reorderable (GtkTreeView + tree_view, gboolean reorderable) 
This function is a convenience function to allow you to reorder models that support the GtkDragSourcelface 
and the GtkDragDestlface. 


Both GtkTreeStore and GtkListStore support these. If reorderable is TRUE, then the user can reorder the 
model by dragging and dropping rows. The developer can listen to these changes by connecting to the 
model’s row_inserted and row_deleted signals. 


This function does not give you any degree of control over the order — any reordering is allowed. If more 
control is needed, you should probably handle drag and drop manually. 
Parameters: 


tree_view [in] A GtkTreeView 


reorderable [in] TRUE, if the tree can be reordered. 


Returns: 


void 


6.52.3.73 void gtk_tree_view_set_row_separator_func (GtkTreeView x tree_view, 
GtkTreeViewRowSeparatorFunc func, gpointer data, GtkDestroyNotify destroy) 


Sets the row separator function, which is used to determine whether a row should be drawn as a separator. 


If the row separator function is NULL, no separators are drawn. This is the default value. 


Parameters: 


tree_view [in] A GtkTreeView 

func [in] a GtkTree ViewRowSeparatorFun 
data [in] user data to pass to func, or NULL 
destroy [in] destroy notifier for data, or NULL 


Returns: 


void 
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6.52.3.74 void gtk_tree_view_set_rubber_banding (GtkTreeView > tree_view, gboolean enable) 


Enables or disables rubber banding in tree_view. 

If the selection mode is GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select 
multiple rows by dragging the mouse. 

Parameters: 


tree_view [in] A GtkTreeView 
enable [in] TRUE to enable rubber banding 


Returns: 


void 


6.52.3.75 void gtk_tree_view_set_rules_hint (GtkTreeView + tree_view, gboolean setting) 


This function tells GTK+ that the user interface for your application requires users to read across tree rows 
and associate cells with one another. 


By default, GTK+ will then render the tree with alternating row colors. Do not use it just because you 
prefer the appearance of the ruled tree; that's a question for the theme. Some themes will draw tree rows 
in alternating colors even when rules are turned off, and users who prefer that appearance all the time can 
choose those themes. You should call this function only as a semantic hint to the theme engine that your tree 
makes alternating colors useful from a functional standpoint (since it has lots of columns, generally). 


Parameters: 


tree_view [in] A GtkTreeView 


setting [in] TRUE if the tree requires reading across rows 


Returns: 


void 


6.52.3.76 void gtk_tree_view_set_search_column (GtkTreeView + tree_view, gint column) 


Sets column as the column where the interactive search code should search in. 


If the sort column is set, users can use the "start-interactive-search" key binding to bring up search popup. 
The enable-search property controls whether simply typing text will also start an interactive search. 


Note that column refers to a column of the model. 


Parameters: 
tree_view [in] A GtkTreeView 


column [in] the column of the model to search in, or -1 to disable searching 


Returns: 


void 
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6.52.3.77 void gtk_tree_view_set_search_entry (GtkTreeView « tree_view, GtkEntry + entry) 


Sets the entry which the interactive search code will use for this tree_view. 

This is useful when you want to provide a search entry in our interface at all time at a fixed position. 
Passing NULL for entry will make the interactive search code use the built-in popup entry again. 
Parameters: 


tree_view [in] A GtkTreeView 


entry [in] the entry the interactive search code of tree_view should use or NULL 


Returns: 


void 


6.52.3.78 void gtk_tree_view_set_search_equal_func (GtkTreeView x tree_view, 
GtkTreeViewSearchEqualFunc search_equal_func, gpointer search_user_data, 
GtkDestroyNotify search_destroy) 


Sets the compare function for the interactive search capabilities; note that somewhat like stremp() returning 
O for equality GtkTreeViewSearchEqualFunc returns FALSE on matches. 


Parameters: 


tree_view [in] A GtkTreeView 
search_equal_func [in] the compare function to use during the search 
search_user_data [in] user data to pass to search_equal_func, or NULL 


search_destroy [in] Destroy notifier for search_user_data, or NULL 


Returns: 


void 


6.52.3.79 void gtk_tree_view_set_search_position_func (GtkTree View x tree_view, 
GtkTreeViewSearchPositionFunc func, gpointer data, GDestroyNotify destroy) 


Sets the function to use when positioning the seach dialog. 


Parameters: 


tree_view [in] A GtkTreeView 


func [in] the function to use to position the search dialog, or NULL to use the default search position 
function 


data [in] user data to pass to func, or NULL 
destroy [in] Destroy notifier for data, or NULL 


Returns: 


void 
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6.52.3.80 gint gtk_tree_view_set_tree_zoom_flag (GtkTreeView « tree_view, gboolean flag) 


Set treeview zoom flag. 


Selection rows will be displayed in Zoomed manner instead of Focus border. Use should set gtk_tree_- 
view_set_zoom_line_height to specify the Zoom size. 


Parameters: 


tree_view [in] A GtkTreeView 


flag [in] If it’s TRUE, Focused Row will be displayed in Zoomed manner instead of with focus border 
and different selection background. 


Returns: 


1 if succeed, other if fail. 


Since 


LIMO R1 


6.52.3.81 void gtk_tree_view_set_vadjustment (GtkTreeView + tree_view, GtkAdjustment = 
adjustment) 


Sets the GtkAdjustment for the current vertical aspect. 


Parameters: 


tree_view [in] A GtkTreeView 
adjustment The GtkAdjustment to set, or NULL 


Returns: 


void 


6.52.3.82 gint gtk_tree_view_set_zoom_line_height (GtkTreeView + tree_view, guint height) 


Sets treeview zoom line height. 


You can set row height when you use function gtk_tree_view_set_tree_zoom_flag, it also will give use 
default value. 


Parameters: 
tree_view [in] A GtkTreeView 
height [in] The height of the focus row. 
Returns: 
1 if succeed, other if fail. 
Since 
LIMO RI 
Remarks: 


: you must set row height when you use function gtk_tree_view_set_tree_zoom_flag it also will give 
default value 
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6.52.3.83 void gtk_tree_view_tree_to_widget_coords (GtkTreeView + tree_view, gint tx, gint ty, 
gint * wx, gint * wy) 


Converts widget coordinates to coordinates for the tree window (the full scrollable area of the tree). 


Parameters: 
tree_view [in] A GtkTreeView 
tx [in] tree X coordinate 
ty [in] tree Y coordinate 
wx [out] return location for widget X coordinate 


wy [out] return location for widget Y coordinate 


Returns: 


void 


6.52.3.84 void gtk_tree_view_unset_rows_drag_dest (GtkTreeView x tree_view) 


[Deprecated] Undoes the effect of gtk_tree_view_enable_model_drag_source(). 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


void 


Deprecated 
LIMO R1 


6.52.3.85 void gtk_tree_view_unset_rows_drag_source (GtkTreeView + tree_view) 


[Deprecated] Undoes the effect of gtk_tree_view_enable_model_drag_dest(). 


Parameters: 


tree_view [in] A GtkTreeView 


Returns: 


void 


Deprecated 
LIMO R1 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.52 GtkTreeview 551 


6.52.3.86 void gtk_tree_view_widget_to_tree_coords (GtkTreeView + tree_view, gint wx, gint wy, 
gint x tx, gint x ty) 


Converts widget coordinates to coordinates for the tree window (the full scrollable area of the tree). 


Parameters: 
tree_view [in] A GtkTreeView 
wx [in] widget X coordinate 
wy [in] widget Y coordinate 
tx [out] return location for tree X coordinate 


ty [out] return location for tree Y coordinate 


Returns: 


void 
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6.53 GtkCellView 


6.53.1 Detailed Description 


A GtkCellView displays a single row of a GtkTreeModel, using cell renderers just like GtkTree View. 


GtkCellView doesn’t support some of the more complex features of GtkTree View, like cell editing and 
drag and drop. 


Data Structures 


e struct _GtkCellView 


GtkCellView instance structure. 


e struct _GtkCellViewClass 


GtkCellView instance class structure. 


Functions 


GtkWidget * gtk_cell_view_new (void) 
Creates a new GtkCellView widget. 


GtkWidget * gtk_cell_view_new_with_text (const gchar xtext) 


Creates a new GtkCellView widget, adds a GtkCellRendererText to it, and makes its show text. 


GtkWidget * gtk_cell_view_new_with_markup (const gchar «markup) 


Creates a new GtkCellView widget, adds a GtkCellRendererText to it, and makes its show markup. 


GtkWidget x gtk_cell_view_new_with_pixbuf (GdkPixbuf x*pixbuf) 
Creates a new GtkCellView widget, adds a GtkCellRendererPixbuf to it, and makes its show pixbuf. 


void gtk_cell_view_set_model (GtkCell View *cell_view, GtkTreeModel *model) 


Sets the model for cell_view. 


void gtk_cell_view_set_displayed_row (GtkCellView xcell_view, GtkTreePath *path) 
Sets the row of the model that is currently displayed by the GtkCellView. 


GtkTreePath * gtk_cell_view_get_displayed_row (GtkCell View x*cell_view) 


Returns a GtkTreePath referring to the currently displayed row. 


gboolean gtk_cell_view_get_size_of_row (GtkCell View *cell_view, GtkTreePath «path, GtkRequi- 
sition *requisition) 


Sets requisition to the size needed by cell_view to display the model row pointed to by path. 


void gtk_cell_view_set_background_color (GtkCell View *cell_view, const GdkColor *color) 


Sets the background color of view. 


GList * gtk_cell_view_get_cell_renderers (GtkCell View *cell_view) 


Returns the cell renderers which have been added to cell_view. 
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6.53.2 Function Documentation 


6.53.2.1 GListx gtk_cell_view_get_cell_renderers (GtkCell View x cell_view) 


Returns the cell renderers which have been added to cell_view. 


Parameters: 


pixbuf [in] a GtkCellView 


Returns: 


a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed 
with g_list_free() when no longer needed. 


6.53.2.2 GtkTreePath« gtk_cell_view_get_displayed_row (GtkCellView x cell_view) 


Returns a GtkTreePath referring to the currently displayed row. 


If no row is currently displayed, NULL is returned. 


Parameters: 


cell_view [in] a GtkCellView 


Returns: 


the currently displayed row or NULL 


6.53.2.3 gboolean gtk_cell_view_get_size_of_row (GtkCellView x cell_view, GtkTreePath x path, 
GtkRequisition * requisition) 


Sets requisition to the size needed by cell_view to display the model row pointed to by path. 


Parameters: 


pixbuf [in] a GtkCell View 
path [in] a GtkTreePath 


requisition [in] return location for the size 


Returns: 


TRUE 


6.53.2.4 GtkWidget» gtk_cell_view_new (void) 
Creates a new GtkCellView widget. 


Returns: 


A newly created GtkCell View widget 
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6.53.2.5 GtkWidget» gtk_cell_view_new_with_markup (const gchar x markup) 


Creates a new GtkCellView widget, adds a GtkCellRendererText to it, and makes its show markup. 


The text can text can be marked up with the Pango text markup language. 


Parameters: 


markup [in] the text to display in the cell view 


Returns: 


A newly created GtkCell View widget. 


6.53.2.6 GtkWidget* gtk_cell_view_new_with_pixbuf (GdkPixbuf x pixbuf) 


Creates a new GtkCellView widget, adds a GtkCellRendererPixbuf to it, and makes its show pixbuf. 


Parameters: 


pixbuf [in] the image to display in the cell view 


Returns: 


A newly created GtkCell View widget. 


6.53.2.7 GtkWidget* gtk_cell_view_new_with_text (const gchar x text) 


Creates a new GtkCellView widget, adds a GtkCellRendererText to it, and makes its show text. 


Parameters: 


text [in] the text to display in the cell view 


Returns: 


A newly created GtkCell View widget. 


6.53.2.8 void gtk_cell_view_set_background_color (GtkCellView x cell_view, const GdkColor x 
color) 


Sets the background color of view. 


Parameters: 


cell_view [in] a GtkCellView 


color [in] the new background color 


Returns: 


void 
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6.53.2.9 void gtk_cell_view_set_displayed_row (GtkCellView x cell_view, GtkTreePath + path) 


Sets the row of the model that is currently displayed by the GtkCell View. 

If the path is unset, then the contents of the cellview "stick" at their last value; this is not normally a desired 
result, but may be a needed intermediate state if say, the model for the GtkCellView becomes temporarily 
empty. 

Parameters: 


cell_view [in] a GtkCellView 
path [in] a GtkTreePath or NULL to unset. 


Returns: 


void 


6.53.2.10 void gtk_cell_view_set_model (GtkCell View x cell_view, GtkTreeModel * model) 


Sets the model for cell_view. 


If cell_view already has a model set, it will remove it before setting the new model. If model is NULL, 
then it will unset the old model. 


Parameters: 


cell_view [in] a GtkCellView 
model [in] a GtkTreeModel 


Returns: 


void 
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6.54 GtkIconView 


6.54.1 Detailed Description 


GtkIconView provides an alternative view on a list model, displays the model as a grid of icons with labels. 


Like GtkTree View, it allows to select one or multiple items (depending on the selection mode, see gtk_- 
icon_view_set_selection_mode()). 


‘Icon view 


NL 


[as | [a > aa 


Figure 6.13: GtkIconView 


Code Example: 


form = gtk_form_new(); 

icon_view = gtk_icon_view_new(); 
gtk_icon_view_set_row_spacing (icon_view, 4); 
gtk_icon_view_set_column_spacing (icon_view, 4); 
gtk_icon_view_set_margin (icon_view, Ja 

model = create_model (); 
gtk_icon_view_set_model (GTK_ICON_VIEW (icon_view), model); 
fill_model (model); 


gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (icon_view), cell, FALSE); 
g_object_set (cell, "activatable", TRUE, NULL); 
gtk_cell_layout_set_attributes (GTK_CELL LAYOUT (icon_view), 


cell, "active", 4, NULL); 
g_signal_connect (cell, "toggled", G_ CALLBACK (toggled), model); 


cell = gtk_cell_renderer_pixbuf_new (); 
gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (icon_view), cell, FALSE); 
g_object_set (cell, "follow-state", TRUE, NULL); 
gtk_cell_layout_set_attributes (GTK_CELL LAYOUT (icon_view), 

cell, "pixbuf", 0, NULL); 
gtk_cell_renderer_pixbuf_set_is_scale((GtkCellRendererPixbuf x*)cell, TRUE); 
gtk_cell_renderer_pixbuf_set_scale_sb((GtkCellRendererPixbuf *)cell, TRUE); 
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cell = gtk_cell_renderer_pixbuf_new (); 


gtk_cell_layout_pack_start (GTK_CELL_ LAYOUT (icon_view), cell, 
g_object_set (cell, 
"follow-state", TRUE, 
NULL); 
gtk_cell_layout_set_attributes (GTK_CELL LAYOUT (icon_view), 
cell, "pixbuf", 1, NULL); 
cell = gtk_cell_renderer_pixbuf_new (); 
gtk_cell_layout_pack_start (GTK_CELL_ LAYOUT (icon_view), cell, 
g_object_set (cell, 
"follow-state", TRUE, 
NULL); 
gtk_cell_layout_set_attributes (GTK_CELL_ LAYOUT (icon_view), 
cell, "pixbuf", 5, NULL); 


gtk_form_contain_add(form, icon_view); 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkIconView 


GtkIconView instance structure. 


e struct _GtkIconViewClass 


GtkIconView instance class structure. 


Functions 


e GtkWidget * gtk_icon_view_new (void) 


Creates a new GtkIconView widget. 


FALSE) ; 


FALSE) ; 


e GtkWidget * gtk_icon_view_new_with_model (GtkTreeModel *model) 


Creates a new GtkIconView widget with the model model. 


e void gtk_icon_view_set_model (GtkIconView *icon_view, GtkTreeModel x*model) 


Sets the model for a GtkIconView. 


e GtkTreeModel * gtk_icon_view_get_model (GtkIconView *icon_view) 


Returns the model the GtkIconView is based on. 


e gint gtk_icon_view_get_icon_height (GtkIconView *icon_view) 


Gets the height of unfocused item of a GtkIconView widget. 


e void gtk_icon_view_set_text_column (GtkIconView *icon_view, gint column) 


Sets the column with text for icon_view to be column. 


e gint gtk_icon_view_get_text_column (GtkIconView *icon_view) 


Returns the column with text for icon_view. 


e void gtk_icon_view_set_markup_column (GtkIconView *icon_view, gint column) 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


558 


Module Documentation 


Sets the column with markup information for icon_view to be column. 


gint gtk_icon_view_get_markup_column (GtkIconView *icon_view) 


Returns the column with markup text for icon_view. 


void gtk_icon_view_set_pixbuf_column (GtkIconView *icon_view, gint column) 


Sets the column with pixbufs for icon_view to be column. 


gint gtk_icon_view_get_pixbuf_column (GtkIconView *icon_view) 


Returns the column with pixbufs for icon_view. 


void gtk_icon_view_set_orientation (GtkIconView *icon_view, GtkOrientation orientation) 


Sets the orientation property which determines whether the labels are drawn beside the icons instead of 
below. 


GtkOrientation gtk_icon_view_get_orientation (GtkIcon View *icon_view) 


Returns the value of the orientation property which determines whether the labels are drawn beside the 
icons instead of below. 


void gtk_icon_view_set_columns (GtkIconView *icon_view, gint columns) 


Sets the columns property which determines in how many columns the icons are arranged. 


gint gtk_icon_view_get_columns (GtkIconView *icon_view) 


Returns the columns property which determines in how many columns the icons are arranged. 


void gtk_icon_view_set_item_width (GtkIconView *icon_view, gint item_width) 


Sets the item-width property which specifies the width to use for each item. 


gint gtk_icon_view_get_item_width (GtkIcon View x*icon_view) 


Returns the value of the item-width property. 


void gtk_icon_view_set_spacing (GtkIconView x*icon_view, gint spacing) 


Sets the spacing property which specifies the space which is inserted between the cells (That is the icon and 
the text) of an item. 


gint gtk_icon_view_get_spacing (GtkIcon View *icon_view) 


Returns the value of the spacing property. 


void gtk_icon_view_set_row_spacing (GtkIconView *icon_view, gint row_spacing) 


Sets the row-spacing property which specifies the space which is inserted between the rows of the icon view. 


gint gtk_icon_view_get_row_spacing (GtkIconView *icon_view) 


Returns the value of the row-spacing property. 


void gtk_icon_view_set_column_spacing (GtkIconView *icon_view, gint column_spacing) 


Sets the column-spacing property which specifies the space which is inserted between the columns of the 
icon view. 


gint gtk_icon_view_get_column_spacing (GtkIconView *icon_view) 


Returns the value of the column-spacing property. 
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e void gtk_icon_view_set_margin (GtkIconView *icon_view, gint margin) 


Sets the margin property which specifies the space which is inserted at the top, bottom, left and right of the 
icon view. 


e gint gtk_icon_view_get_margin (GtkIconView x*icon_view) 


Returns the value of the margin property.s. 


e GtkTreePath * gtk_icon_view_get_path_at_pos (GtkIconView *icon_view, gint x, gint y) 


Finds the path at the point (x, y), relative to widget coordinates. 


e gboolean gtk_icon_view_get_item_at_pos (GtkIconView *icon_view, gint x, gint y, GtkTreePath 
xxpath, GtkCellRenderer **cell) 


Finds the path at the point (x, y), relative to widget coordinates. 


e gboolean gtk_icon_view_get_visible_range (GtkIconView *icon_view, GtkTreePath *«start_path, 
GtkTreePath **end_path) 


Sets start_path and end_path to be the first and last visible path. 


e void gtk_icon_view_selected_foreach (GtkIconView x*icon_view, GtkIconViewForeachFunc func, 
gpointer data) 


Calls a function for each selected icon. 


e void gtk_icon_view_set_selection_mode (GtkIconView *icon_view, GtkSelectionMode mode) 


Sets the selection mode of the icon_view. 


e GtkSelectionMode gtk_icon_view_get_selection_mode (GtkIconView *icon_view) 


Gets the selection mode of the icon_view. 


e void gtk_icon_view_select_path (GtkIconView *icon_view, GtkTreePath xpath) 


Selects the row at path. 


e void gtk_icon_view_unselect_path (GtkIconView *icon_view, GtkTreePath path) 


Unselects the row at path. 


e gboolean gtk_icon_view_path_is_selected (GtkIconView *icon_view, GtkTreePath xpath) 


Returns TRUE if the icon pointed to by path is currently selected. 


e GList * gtk_icon_view_get_selected_items (GtkIconView *icon_view) 


Creates a list of paths of all selected items. 


e void gtk_icon_view_select_all (GtkIconView +icon_view) 


Selects all the icons. 


e void gtk_icon_view_unselect_all (GtkIconView *icon_view) 


Unselects all the icons. 


e void gtk_icon_view_item_activated (GtkIconView *icon_view, GtkTreePath xpath) 


Activates the item determined by path. 


e void gtk_icon_view_set_cursor (GtkIconView x*icon_view, GtkTreePath xpath, GtkCellRenderer 
«cell, gboolean start_editing) 
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Sets the current keyboard focus to be at path, and selects it. 


gboolean gtk_icon_view_get_cursor (GtkIconView x*icon_view, GtkTreePath *x*path, GtkCellRen- 
derer xxcell) 


Fills in path and cell with the current cursor path and cell. 


void gtk_icon_view_scroll_to_path (GtkIconView x*icon_view, GtkTreePath «path, gboolean use_- 
align, gfloat row_align, gfloat col_align) 


Moves the alignments of icon_view to the position specified by path. 


void gtk icon view_enable_model drag_source (GtkIconView »*icon_view, GdkModifierType 
start_button_mask, const GtkTargetEntry «targets, gint n_targets, GdkDragAction actions) 


[Deprecated] Turns icon_view into a drag source for automatic DND. 


void gtk_icon_view_enable_model_drag_dest (GtkIconView x*icon_view, const GtkTargetEntry 
*targets, gint n_targets, GdkDragAction actions) 


[Deprecated] Turns icon_view into a drop destination for automatic DND. 


void gtk_icon_view_unset_model_drag_source (GtkIconView *icon_view) 


[Deprecated] Undoes the effect of gtk_icon_view_enable_model_drag_source(). 


void gtk_icon_view_unset_model_drag_dest (GtkIconView *icon_view) 


[Deprecated] Undoes the effect of gtk_icon_view_enable_model_drag_dest(). 


void gtk_icon_view_set_reorderable (GtkIconView x*icon_view, gboolean reorderable) 
[Deprecated] This function is a convenience function to allow you to reorder models that support the Gtk- 
TreeDragSourcelface and the GtkTreeDragDestlface. 

gboolean gtk_icon_view_get_reorderable (GtkIconView *icon_view) 


[Deprecated] Retrieves whether the user can reorder the list via drag-and-drop. 


void gtk_icon_view_set_drag_dest_item (GtkIconView *icon_view, GtkTreePath «path, GtkIcon- 
ViewDropPosition pos) 


[Deprecated] Sets the item that is highlighted for feedback. 


void gtk_icon_view_get_drag_dest_item (GtkIconView +icon_view, GtkTreePath **path, GtkIcon- 
ViewDropPosition xpos) 


[Deprecated] Gets information about the item that is highlighted for feedback. 


gboolean gtk_icon_view_get_dest_item_at_pos (GtkIconView *icon_view, gint drag_x, gint drag_y, 
GtkTreePath **path, GtkIconViewDropPosition xpos) 


[Deprecated] Determines the destination item for a given position. 


GdkPixmap * gtk_icon_view_create_drag_icon (GtkIconView *icon_view, GtkTreePath xpath) 


[Deprecated] Creates a GdkPixmap representation of the item at path. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.54 GtkIconView 561 


6.54.2 Function Documentation 


6.54.2.1 GdkPixmap« gtk_icon_view_create_drag_icon (GtkIconView x icon_view, GtkTreePath x 
path) 


[Deprecated] Creates a GdkPixmap representation of the item at path. 


This image is used for a drag icon. 


Parameters: 


< icon_view A GtkIconView. 


— path a GtkTreePath in icon_view 


Returns: 


a newly-allocated pixmap of the drag icon. 


Deprecated 
LIMO R1 


6.54.2.2 void gtk_icon_view_enable_model_drag_dest (GtkIconView x icon_view, const 
GtkTargetEntry * targets, gint n_targets, GdkDragAction actions) 


[Deprecated] Turns icon_view into a drop destination for automatic DND. 


Parameters: 


< icon_view A GtkIconView. 
— targets the table of targets that the drag will support 
— n_targets he number of items in targetss 


— actionss the bitmask of possible actions for a drag to this widget 
Returns: 

void 
Deprecated 

LIMO R1 


6.54.2.3 void gtk_icon_view_enable_model_drag_source (GtkIconView + icon_view, 
GdkModifierType start_button_mask, const GtkTargetEntry x targets, gint n_targets, 
GdkDragAction actions) 


[Deprecated] Turns icon_view into a drag source for automatic DND. 


Parameters: 


< icon_view a GtkIconTree View 


< start_button_mask Mask of allowed buttons to start drag 
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— targets the table of targets that the drag will supports 
— n_targets the number of items in targets 
— actions the bitmask of possible actions for a drag from this widget 


Returns: 
void 
Deprecated 
LIMO RI 


6.54.2.4 gint gtk_icon_view_get_column_spacing (GtkIcon View x icon_view) 


Returns the value of the column-spacing property. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


the space between columns 


6.54.2.5 gint gtk_icon_view_get_columns (GtkIconView x icon_view) 


Returns the columns property which determines in how many columns the icons are arranged. 
If columns is -1, the number of columns will be chosen automatically to fill the available area. 
Parameters: 


< icon_view A GtkIconView. 


Returns: 


the number of columns, or -1 


6.54.2.6 gboolean gtk_icon_view_get_cursor (GtkIconView + icon_view, GtkTreePath x* path, 
GtkCellRenderer xx cell) 
Fills in path and cell with the current cursor path and cell. 


If the cursor isn’t currently set, then path will be NULL. If no cell currently has focus, then *cell will be 
NULL. 


The returned GtkTreePath must be freed with gtk_tree_path_free(). 


Parameters: 
— icon_view A GtkIconView. 
> path Return location for the current cursor path, or NULL 
— cell Return location the current focus cell, or NULL 
Returns: 


TRUE if the cursor is set. 
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6.54.2.7 gboolean gtk_icon_view_get_dest_item_at_pos (GtkIconView x icon_view, gint drag_x, 
gint drag_y, GtkTreePath xx path, GtkIconViewDropPosition « pos) 


[Deprecated] Determines the destination item for a given position. 


Parameters: 


— icon_view A GtkIconView. 

— drag_x the position to determine the destination item for 
— drag_x the position to determine the destination item for 
— path Return location for the path of the item, or NULL. 
— pos Return location for the drop position, or NULLs 


Returns: 


whether there is an item at the given position. 


Deprecated 
LIMO R1 


6.54.2.8 void gtk_icon_view_get_drag_dest_item (GtkIcon View x icon_view, GtkTreePath «+ path, 
GtkIcon ViewDropPosition x pos) 


[Deprecated] Gets information about the item that is highlighted for feedback. 


Parameters: 


< icon_view A GtkIconView. 
— path Return location for the path of the highlighted item, or NULL. 
— pos Return location for the drop position, or NULL 


Returns: 
void 
Deprecated 
LIMO R1 


6.54.2.9 gint gtk_icon_view_get_icon_height (GtkIconView x icon_view) 


Gets the height of unfocused item of a GtkIcon View widget. 


Parameters: 

< icon_view A GtkIconView. 
Returns: 

The height of the icons. 


Since 


LIMO R1 
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6.54.2.10  gboolean gtk_icon_view_get_item_at_pos (GtkIconView * icon_view, gint x, gint y, 
GtkTreePath «* path, GtkCellRenderer «+ cell) 


Finds the path at the point (x, y), relative to widget coordinates. 


In contrast to gtk_icon_view_get_path_at_pos(), this function also obtains the cell at the specified position. 
The returned path should be freed with gtk_tree_path_free(). 


Parameters: 


< icon_view A GtkIconView. 

— x The x position to be identified 

— y The y position to be identified 

> path Return location for the path, or NULL 

> cell Return location for the renderer responsible for the cell at (x, y), or NULL 


Returns: 


TRUE if an item exists at the specified position 


6.54.2.11 gint gtk_icon_view_get_item_width (GtkIconView x icon_view) 


Returns the value of the item-width property. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


the width of a single item, or -1 


6.54.2.12 gint gtk_icon_view_get_margin (GtkIconView « icon_view) 


Returns the value of the margin property.s. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


the space at the borders 


6.54.2.13 gint gtk_icon_view_get_markup_column (GtkIconView * icon_view) 


Returns the column with markup text for icon_view. 


Parameters: 
— icon_view A GtkIconView. 


Returns: 


the markup column, or -1 if it’s unset. 
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6.54.2.14 GtkTreeModel« gtk_icon_view_get_model (GtkIcon View x icon_view) 


Returns the model the GtkIconView is based on. 


Returns NULL if the model is unset. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


A GtkTreeModel, or NULL if none is currently being used. 


6.54.2.15 GtkOrientation gtk_icon_view_get_orientation (GtkIconView * icon_view) 


Returns the value of the orientation property which determines whether the labels are drawn beside the 
icons instead of below. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


the relative position of texts and icons 


6.54.2.16 GtkTreePathx gtk_icon_view_get_path_at_pos (GtkIconView * icon_view, gint x, gint y) 


Finds the path at the point (x, y), relative to widget coordinates. 


See gtk_icon_view_get_item_at_pos(), if you are also interested in the cell at the specified position. 


Parameters: 


< icon_view A GtkIconView. 
— x The x position to be identified 


— y The y position to be identified 


Returns: 


The GtkTreePath corresponding to the icon or NULL if no icon exists at that position. 


6.54.2.17 gint gtk_icon_view_get_pixbuf_column (GtkIconView x icon_view) 


Returns the column with pixbufs for icon_view. 


Parameters: 


— icon_view A GtkIconView. 


Returns: 


the pixbuf column, or -1 if it’s unset. 
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6.54.2.18 gboolean gtk_icon_view_get_reorderable (GtkIconView x icon_view) 


[Deprecated] Retrieves whether the user can reorder the list via drag-and-drop. 


See gtk_icon_view_set_reorderable(). 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


TRUE if the list can be reordered. 


Deprecated 
LIMO R1 


6.54.2.19 gint gtk_icon_view_get_row_spacing (GtkIconView * icon_view) 


Returns the value of the row-spacing property. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


the space between rows 


6.54.2.20 GList« gtk_icon_view_get_selected_items (GtkIconView x icon_view) 


Creates a list of paths of all selected items. 


Additionally, if you are planning on modifying the model after calling this function, you may want to 
convert the returned list into a list of GtkTreeRowReferences. To do this, you can use gtk_tree_row_- 
reference_new(). 


To free the return value, use: 


g_list_foreach (list, gtk_tree_path_free, NULL); 
g_list_free (list); 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


A GList containing a GtkTreePath for each selected row. 
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6.54.2.21 GtkSelectionMode gtk_icon_view_get_selection_mode (GtkIconView x icon_view) 
Gets the selection mode of the icon_view. 


Parameters: 


— icon_view A GtkIconView. 


Returns: 


the current selection mode 


6.54.2.22 gint gtk_icon_view_get_spacing (GtkIconView « icon_view) 
Returns the value of the spacing property. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


the space between cells 


6.54.2.23 gint gtk_icon_view_get_text_column (GtkIconView + icon_view) 


Returns the column with text for icon_view. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


the text column, or -1 if it’s unset. 


6.54.2.24 gboolean gtk_icon_view_get_visible_range (GtkIconView « icon_view, GtkTreePath «x 
start_path, GtkTreePath *x end_path) 


Sets start_path and end_path to be the first and last visible path. 
Note that there may be invisible paths in between. 


Both paths should be freed with gtk_tree_path_free() after use. 


Parameters: 


— icon_view A GtkIconView. 
> start_path Return location for start of region, or NULL 


— end_path Return location for end of region, or NULL 


Returns: 


TRUE, if valid paths were placed in start_path and end_path 
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6.54.2.25 void gtk_icon_view_item_activated (GtkIconView + icon_view, GtkTreePath + path) 


Activates the item determined by path. 


Parameters: 
— icon_view A GtkIconView. 


— path The GtkTreePath to be activated 


Returns: 


void 


6.54.2.26 GtkWidget« gtk_icon_view_new (void) 


Creates a new GtkIconView widget. 


Returns: 


A newly created GtkIcon View widget 


6.54.2.27 GtkWidget gtk_icon_view_new_with_model (GtkTreeModel x model) 


Creates a new GtkIconView widget with the model model. 


Parameters: 


< model The model. 


Returns: 


A newly created GtkIcon View widget. 


6.54.2.28 gboolean gtk_icon_view_path_is_selected (GtkIconView + icon_view, GtkTreePath x 
path) 


Returns TRUE if the icon pointed to by path is currently selected. 


If path does not point to a valid location, FALSE is returned. 


Parameters: 
< icon_view A GtkIconView. 


— path A GtkTreePath to check selection on. 


Returns: 


TRUE if path is selected. 
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6.54.2.29 void gtk_icon_view_scroll_to_path (GtkIconView * icon_view, GtkTreePath + path, 
gboolean use_align, gfloat row_align, gfloat col_align) 


Moves the alignments of icon_view to the position specified by path. 


row_align determines where the row is placed, and col_align determines where column is placed. Both are 
expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 
means center. 


If use_align is FALSE, then the alignment arguments are ignored, and the tree does the minimum amount 
of work to scroll the item onto the screen. This means that the item will be scrolled to the edge closest to 
1ts current position. If the item is currently visible on the screen, nothing is done. 


This function only works if the model is set, and path is a valid row on the model. If the model changes 
before the icon_view is realized, the centered path will be modified to reflect this change. 


Parameters: 


— icon_view A GtkIconView. 

— path The path of the item to move to. 

— use_align whether to use alignment arguments, or FALSE. 

— row_align The vertical alignment of the item specified by path. 


— col_align The horizontal alignment of the item specified by path. 


Returns: 


void 


6.54.2.30 void gtk_icon_view_select_all (GtkIconView x icon_view) 


Selects all the icons. 


icon_view must has its selection mode set to GTK_SELECTION_MULTIPLE. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


void 


6.54.2.31 void gtk_icon_view_select_path (GtkIconView x icon_view, GtkTreePath « path) 


Selects the row at path. 


Parameters: 


— icon_view A GtkIconView. 
— path The GtkTreePath to be selected. 


Returns: 


void 
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6.54.2.32 void gtk_icon_view_selected_foreach (GtkIconView * icon_view, 
GtkIconViewForeachFunc func, gpointer data) 


Calls a function for each selected icon. 


Note that the model or selection cannot be modified from within this function. 


Parameters: 
— icon_view A GtkIconView. 
— func The funcion to call for each selected icon.. 


— data User data to pass to the function. 


Returns: 


void 


6.54.2.33 void gtk_icon_view_set_column_spacing (GtkIconView x icon_view, gint 
column_spacing) 


Sets the column-spacing property which specifies the space which is inserted between the columns of the 
icon view. 


Parameters: 


< icon_view A GtkIconView. 


— column_spacing the column spacing 


Returns: 


void 


6.54.2.34 void gtk_icon_view_set_columns (GtkIconView x icon_view, gint columns) 


Sets the columns property which determines in how many columns the icons are arranged. 


If columns is -1, the number of columns will be chosen automatically to fill the available area. 


Parameters: 
— icon_view A GtkIconView. 


< columns the number of columns 


Returns: 


void 


6.54.2.35 void gtk_icon_view_set_cursor (GtkIconView x icon_view, GtkTreePath x path, 
GtkCellRenderer + cell, gboolean start_editing) 


Sets the current keyboard focus to be at path, and selects it. 
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This is useful when you want to focus the user’s attention on a particular item. If cell is not NULL, then 
focus is given to the cell specified by it. Additionally, if start_editing is TRUE, then editing should be 
started in the specified cell. 


This function is often followed by gtk_widget_grab_focus (icon_view) in order to give keyboard focus to 
the widget. Please note that editing can only happen when the widget is realized. 
Parameters: 

< icon_view A GtkIconView. 

— path A GtkTreePath 

< cell One of the cell renderers of icon_view, or NULL 


— start_editing TRUE if the specified cell should start being edited. 


Returns: 


void 


6.54.2.36 void gtk_icon_view_set_drag_dest_item (GtkIconView * icon_view, GtkTreePath x path, 
GtkIconViewDropPosition pos) 


[Deprecated] Sets the item that is highlighted for feedback. 


Parameters: 


— icon_view A GtkIconView. 
— path The path of the item to highlight, or NULL. 


— pos Specifies where to drop, relative to the item 


Returns: 


void 


Deprecated 
LIMO R1 


6.54.2.37 void gtk_icon_view_set_item_width (GtkIconView x icon_view, gint item_width) 


Sets the item-width property which specifies the width to use for each item. 


If it is set to -1, the icon view will automatically determine a suitable item size. 


Parameters: 


< icon_view A GtkIconView. 


< item_width the width for each item 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


572 Module Documentation 


6.54.2.38 void gtk_icon_view_set_margin (GtkIconView x icon_view, gint margin) 


Sets the margin property which specifies the space which is inserted at the top, bottom, left and right of the 
icon view. 
Parameters: 

— icon_view A GtkIconView. 


— margin the margin 


Returns: 


void 


6.54.2.39 void gtk_icon_view_set_markup_column (GtkIconView x icon_view, gint column) 


Sets the column with markup information for icon_view to be column. 


The markup column must be of type G_TYPE_STRING. If the markup column is set to something, it 
overrides the text column set by gtk_icon_view_set_text_column(). 


Parameters: 
< icon_view A GtkIconView. 


— column A column in the currently used model, or -1 to display no text 


Returns: 


void 


6.54.2.40 void gtk_icon_view_set_model (GtkIconView x icon_view, GtkTreeModel « model) 


Sets the model for a GtkIcon View. 


If the icon_view already has a model set, it will remove it before setting the new model. If model is NULL, 
then it will unset the old model. 


Parameters: 
< icon_view A GtkIconView. 


< model The model. 


Returns: 


void 


6.54.2.41 void gtk_icon_view_set_orientation (GtkIconView + icon_view, GtkOrientation 
orientation) 


Sets the orientation property which determines whether the labels are drawn beside the icons instead of 
below. 
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Parameters: 


< icon_view A GtkIconView. 


< orientation the relative position of texts and icons 


Returns: 


the pixbuf column, or -1 if it’s unset. 


6.54.2.42 void gtk_icon_view_set_pixbuf_column (GtkIconView + icon_view, gint column) 


Sets the column with pixbufs for icon_view to be column. 


The pixbuf column must be of type GDK_TYPE_PIXBUF 


Parameters: 


< icon_view A GtkIconView. 


— column A column in the currently used model, or -1 to disable 


Returns: 


void 


6.54.2.43 void gtk_icon_view_set_reorderable (GtkIconView * icon_view, gboolean reorderable) 
[Deprecated] This function is a convenience function to allow you to reorder models that support the 
GtkTreeDragSourcelface and the GtkTreeDragDestlface. 


Both GtkTreeStore and GtkListStore support these. If reorderable is TRUE, then the user can reorder the 
model by dragging and dropping rows. The developer can listen to these changes by connecting to the 
model’s row_inserted and row_deleted signals. 


This function does not give you any degree of control over the order — any reordering is allowed. If more 
control is needed, you should probably handle drag and drop manually. 


Parameters: 


< icon_view A GtkIconView. 


— reorderable TRUE, if the list of items can be reordered. 


Returns: 


void 


Deprecated 
LIMO R1 


6.54.2.44 void gtk_icon_view_set_row_spacing (GtkIconView x icon_view, gint row_spacing) 


Sets the row-spacing property which specifies the space which is inserted between the rows of the icon 
view. 
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Parameters: 


— icon_view A GtkIconView. 


— row_spacing the row spacing 


Returns: 


void 


6.54.2.45 void gtk_icon_view_set_selection_mode (GtkIconView x icon_view, GtkSelectionMode 
mode) 


Sets the selection mode of the icon_view. 


Parameters: 


— icon_view A GtkIconView. 


< mode The selection mode. 


Returns: 


void 


6.54.2.46 void gtk_icon_view_set_spacing (GtkIconView x icon_view, gint spacing) 


Sets the spacing property which specifies the space which is inserted between the cells (That is the icon 
and the text) of an item. 


Parameters: 


— icon_view A GtkIconView. 


— spacing the spacing 


Returns: 


void 


6.54.2.47 void gtk_icon_view_set_text_column (GtkIconView x icon_view, gint column) 


Sets the column with text for icon_view to be column. 


The text column must be of type G_TYPE_STRING. 


Parameters: 


< icon_view A GtkIconView. 


— column A column in the currently used model, or -1 to display no text 


Returns: 


void 
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6.54.2.48 void gtk_icon_view_unselect_all (GtkIconView x icon_view) 


Unselects all the icons. 


Parameters: 


< icon_view A GtkIconView. 


Returns: 


void 


6.54.2.49 void gtk_icon_view_unselect_path (GtkIconView x icon_view, GtkTreePath « path) 


Unselects the row at path. 


Parameters: 


— icon_view A GtkIconView. 
— path The GtkTreePath to be unselected. 


Returns: 


void 


6.54.2.50 void gtk_icon_view_unset_model_drag_dest (GtkIconView x icon_view) 


[Deprecated] Undoes the effect of gtk_icon_view_enable_model_drag_dest(). 


Parameters: 


< icon_view A GtkIconView. 
Returns: 

void 
Deprecated 

LIMO R1 


6.54.2.51 void gtk_icon_view_unset_model_drag_source (GtkIconView * icon_view) 


[Deprecated] Undoes the effect of gtk_icon_view_enable_model_drag_source(). 


Parameters: 


< icon_view A GtkIconView. 
Returns: 

void 
Deprecated 

LIMO RI 
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6.55 GtkTreeSortable 


6.55.1 Detailed Description 


GtkTreeSortable is an interface to be implemented by tree models which support sorting. 


The GtkTreeView uses the methods provided by this interface to sort the model. 


Functions 


e void gtk_tree_sortable_sort_column_changed (GtkTreeSortable «sortable) 


Emits a GtkTreeSortable::sort_column_changed signal on. 


gboolean gtk_tree_sortable_get_sort_column_id (GtkTreeSortable «sortable, gint *sort_column_id, 
GtkSortType *order) 


Fills in sort_column_id and order with the current sort column and the order. 


void gtk_tree_sortable_set_sort_column_id (GtkTreeSortable «sortable, gint sort_column_id, Gtk- 
SortType order) 


Sets the current sort column to be sort_column_id. 


void gtk_tree_sortable_set_sort_func (GtkTreeSortable «sortable, gint sort_column_id, GtkTreelter- 
CompareFunc sort_func, gpointer user_data, GtkDestroyNotify destroy) 


Sets the comparison function used when sorting to be sort_func. 


void gtk_tree_sortable_set_default_sort_func (GtkTreeSortable x*sortable, GtkTreelterCompareFunc 
sort_func, gpointer user_data, GtkDestroyNotify destroy) 


Sets the default comparison function used when sorting to be sort_func. 


gboolean gtk_tree_sortable_has_default_sort_func (GtkTreeSortable x*sortable) 


Returns TRUE if the model has a default sort function. 


6.55.2 Function Documentation 


6.55.2.1 gboolean gtk_tree_sortable_get_sort_column_id (GtkTreeSortable x sortable, gint « 
sort_column_id, GtkSortType * order) 


Fills in sort_column_id and order with the current sort column and the order. 


It returns TRUE unless the sort_column_id is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_- 
ID or GTK_TREE_ SORTABLE _UNSORTED_SORT_COLUMN_ID. 


Parameters: 


sortable [in] a GtkTreeSortable widget. 
sort_column_id [in] The sort column id to be filled in 
order [in] The GtkSortType to be filled in 


Returns: 


TRUE if the sort column is not one of the special sort column ids. 
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6.55.2.2 gboolean gtk_tree_sortable_has_default_sort_func (GtkTreeSortable x sortable) 


Returns TRUE if the model has a default sort function. 


This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default 
state, or not. 


Parameters: 


editable [in] a GtkEditable widget. 


Returns: 


TRUE, if the model has a default sort function 


6.55.2.3 void gtk_tree_sortable_set_default_sort_func (GtkTreeSortable x sortable, 
GtkTreeIterCompareFunc sort_func, gpointer user_data, GtkDestroyNotify destroy) 


Sets the default comparison function used when sorting to be sort_func. 


If the current sort column id of sortable is GTK_TREE SORTABLE DEFAULT_SORT_COLUMN_ ID, 
then the model will sort using this function. If sort_func is NULL, then there will be no default comparison 
function. This means that once the model has been sorted, it can’t go back to the default state. In this case, 
when the current sort column id of sortable is GTK_TREE_ SORTABLE _DEFAULT_SORT_COLUMN_- 
ID, the model will be unsorted. 


Parameters: 


sortable [in] a GtkTreeSortable widget. 

sort_func [in] The comparison function 

user_data [in] User data to pass to sort_func, or NULL 
destroy [in] Destroy notifier of user_data, or NULL 


Returns: 


void 


6.55.2.4 void gtk_tree_sortable_set_sort_column_id (GtkTreeSortable x sortable, gint 
sort_column_id, GtkSortType order) 


Sets the current sort column to be sort_column_id. 


The sortable will resort itself to reflect this change, after emitting a GtkTreeSortable : :sort_column_- 
changed signal. If sort_column_id is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then 
the default sort function will be used, if it is set. 


Parameters: 
sortable [in] a GtkTreeSortable widget. 
sort_column_id [in] the sort column id to set 
order [in] The sort order of the column 
Returns: 


void 
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6.55.2.5 void gtk_tree_sortable_set_sort_func (GtkTreeSortable x sortable, gint sort_column_id, 
GtkTreelterCompareFunc sort_func, gpointer user_data, GtkDestroyNotify destroy) 
Sets the comparison function used when sorting to be sort_func. 


Tf the current sort column id of sortable is the same as sort_column_id, then the model will sort using this 
function. 


Parameters: 


sortable [in] a GtkTreeSortable widget. 

sort_column_id [in] the sort column id to set the function for 
sort_func [in] The comparison function 

user_data [in] User data to pass to sort_func, or NULL 


destroy [in] Destroy notifier of user_data, or NULL 


Returns: 


void 


6.55.2.6 void gtk_tree_sortable_sort_column_changed (GtkTreeSortable x sortable) 


Emits a GtkTreeSortable::sort_column_changed signal on. 


Parameters: 


sortable [in] a GtkTreeSortable widget. 


Returns: 


void 
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6.56 GtkTreeModelSort 


6.56.1 Detailed Description 


The GtkTreeModelSort is a model which implements the GtkTreeSortable interface. 


It does not hold any data itself, but rather is created with a child model and proxies its data. It has identical 
column types to this child model, and the changes in the child are propagated. The primary purpose of this 
model is to provide a way to sort a different model without modifying it. Note that the sort function used 
by GtkTreeModelSort is not guaranteed to be stable. 


The use of this is best demonstrated through an example. In the following sample code we create two 
GtkTreeView widgets each with a view of the same data. As the model is wrapped here by a GtkTreeMod- 
elSort, the two GtkTreeViews can each sort their view of the data without affecting the other. By contrast, 
1f we simply put the same model in each widget, then sorting the first would sort the second. 


Code Example 


{ 

GtkTreeView *tree_viewl; 
GtkTreeView *tree_view2; 
GtkTreeModel *sort_modell; 
GtkTreeModel *sort_model2; 
GtkTreeModel *child_model; 


// get the child model 
child_model = get_my_model (); 


// Create the first tree 
sort_modell = gtk_tree_model_sort_new_with_model (child_model); 
tree_viewl = gtk_tree_view_new_with_model (sort_modell); 


// Create the second tree 
sort_model2 = gtk_tree_model_sort_new_with_model (child_model); 
tree_view2 = gtk_tree_view_new_with_model (sort_model2); 


// Now we can sort the two models independently 

gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_modell), 
COLUMN_1, GTK_SORT_ASCENDING) ; 

gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2), 
COLUMN_1, GTK_SORT_DESCENDING) ; 


} 


@endocde 


To demonstrate how to access the underlying child model from the sort model, 

the next example will be a callback for the GtkTreeSelection "changed" signal. 

In this callback, we get a string from COLUMN_1 of the model. We then modify the string, 
find the same selected row on the child model, and change the row there. 


<b> Code Example</b> 
@code 


void 
selection_changed (GtkTreeSelection *selection, gpointer data) 


{ 


GtkTreeModel *sort_model = NULL; 
GtkTreeModel *child_model; 
GtkTreeIter sort_iter; 
GtkTreeIter child_iter; 

char *some_data = NULL; 

char *modified_data; 


// Get the current selected row and the model. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


580 Module Documentation 


if (! gtk_tree_selection_get_selected (selection, 
&sort_model, 
&sort_iter) ) 
return; 


// Look up the current value on the selected row and get a new value to change it to. 


gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter, 
COLUMN_1, &some_data, 
-1); 


modified_data = change_the_data (some_data) ; 
g_free (some_data) ; 


// Get an iterator on the child model, instead of the sort model. 
gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model), 
£child_iter, 
£sort_iter); 


//Get the child model and change the value of the row. In this example, 
// the child model is a GtkListStore. It could be any other type of model, though. 


child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model) ); 
gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter, 
COLUMN_1, &modified_data, 
-1); 
g_free (modified_data); 
} 


Data Structures 


e struct _GtkTreeModelSort 


GtkTreeModelSort instance structure. 


e struct _GtkTreeModelSortClass 


GtkTreeModelSort instance class structure. 


Functions 


e GtkTreeModel x gtk_tree_model_sort_new_with_model (GtkTreeModel x*child_model) 
Creates a new GtkTreeModel, with child_model as the child model. 


e GtkTreeModel « gtk_tree_model_sort_get_model (GtkTreeModelSort *tree_model) 
Returns the model the GtkTreeModelSort is sorting. 


e GtkTreePath * gtk tree_model_sort_convert_child_path_to_path (GtkTreeModelSort xtree_- 
model_sort, GtkTreePath *child_path) 


Converts child_path to a path relative to tree_model_sort. 


e void gtk tree_model_sort_convert_child_iter_to_iter (GtkTreeModelSort *tree_model_sort, Gtk- 
Treelter *sort_iter, GtkTreelter *child_iter) 


Sets sort_iter to point to the row in tree_model_sort that corresponds to the row pointed at by child_iter. 


e GtkTreePath * gtk tree _model_sort_convert_path_to_child_path (GtkTreeModelSort xtree_- 
model_sort, GtkTreePath *sorted_path) 
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Converts sorted_path to a path on the child model of tree_model_sort. 


e void gtk tree_model_sort_convert_iter_to_child_iter (GtkTreeModelSort *tree_model_sort, Gtk- 
Treelter x*child_iter, GtkTreelter *sorted_iter) 


Sets child_iter to point to the row pointed to by sorted_iter. 


e void gtk_tree_model_sort_reset_default_sort_func (GtkTreeModelSort *tree_model_sort) 


This resets the default sort function to be in the ’unsorted’ state. 


e void gtk_tree_model_sort_clear_cache (GtkTreeModelSort xtree_model_sort) 


This function should almost never be called. 


e gboolean gtk_tree_model_sort_iter_is_valid (GtkTreeModelSort »*tree_model_sort, GtkTreelter 
xiter) 


Checks if the given iter is a valid iter for this GtkTreeModelSort. 


6.56.2 Function Documentation 


6.56.2.1 void gtk_tree_model_sort_clear_cache (GtkTreeModelSort x tree_model_sort) 


This function should almost never be called. 


It clears the tree_model_sort of any cached iterators that haven't been reffed with gtk_tree_model_ref - 
node(). This might be useful if the child model being sorted is static (and doesn't change often) and there 
has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be 
invalid. 


Parameters: 


tree_model_sort [in] A GtkTreeModelSort 


Returns: 


void 


6.56.2.2 void gtk_tree model _sort_convert_child_iter_to_iter (GtkTreeModelSort « 
tree_model_sort, GtkTreelter x sort_iter, GtkTreelter x child_iter) 


Sets sort_iter to point to the row in tree_model_sort that corresponds to the row pointed at by child_iter. 


Parameters: 
tree_model_sort [in] a GtkTreeModelSort 
sort_iter [in] An uninitialized GtkTreelter. 


child_iter [in] A valid GtkTreelter pointing to a row on the child model 


Returns: 


void 
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6.56.2.3 GtkTreePathx gtk_tree_model_sort_convert_child_path_to_path (GtkTreeModelSort x 
tree_model_sort, GtkTreePath x child_path) 


Converts child_path to a path relative to tree_model_sort. 
That is, child_path points to a path in the child model. The returned path will point to the same row in the 
sorted model. If child_path isn't a valid path on the child model, then NULL is returned. 
Parameters: 
tree_model_sort [in] A GtkTreeModelSort 
child_path [in] A GtkTreePath to convert 


Returns: 


A newly allocated GtkTreePath, or NULL 


6.56.2.4 void gtk_tree_model_sort_convert_iter_to_child_iter (GtkTreeModelSort « 
tree_model_sort, GtkTreelter x child_iter, GtkTreelter « sorted_iter) 


Sets child_iter to point to the row pointed to by sorted_iter. 


Parameters: 
tree_model_sort [in] a GtkTreeModelSort 
child_iter [in] An uninitialized GtkTreelter 


sorted_iter [in] A valid GtkTreelter pointing to a row on tree_model_sort. 


Returns: 


void 


6.56.2.5 GtkTreePath« gtk_tree_model_sort_convert_path_to_child_path (GtkTreeModelSort « 
tree_model_sort, GtkTreePath x sorted_path) 


Converts sorted_path to a path on the child model of tree_model_sort. 
That is, sorted_path points to a location in tree_model_sort. The returned path will point to the same 
location in the model not being sorted. If sorted_path does not point to a location in the child model, 
NULL is returned. 
Parameters: 

tree_model_sort [in] a GtkTreeModelSort 


sorted_path [in] A GtkTreePath to convert 


Returns: 


A newly allocated GtkTreePath, or NULL 
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6.56.2.6 GtkTreeModelx gtk_tree_model_sort_get_model (GtkTreeModelSort « tree_model) 


Returns the model the GtkTreeModelSort is sorting. 


Parameters: 


tree_model [in] a GtkTreeModelSort 


Returns: 


the "child model" being sorted 


6.56.2.7 gboolean gtk_tree_model_sort_iter_is_valid (GtkTreeModelSort x tree_model_sort, 
GtkTreelter x iter) 


Checks if the given iter is a valid iter for this GtkTreeModelSort. 


Parameters: 


tree_model_sort [in] a GtkTreeModelSort 
iter [in] A GtkTreelter. 


Returns: 


TRUE if the iter is valid, FALSE if the iter is invalid. This function is slow. Only use it for debugging 
and/or testing purposes. 


6.56.2.8 GtkTreeModelx gtk_tree_model_sort_new_with_model (GtkTreeModel « child_model) 


Creates a new GtkTreeModel, with child_model as the child model. 


Parameters: 


child_model [in] a GtkTreeModel 


Returns: 


A new GtkTreeModel. 


6.56.2.9 void gtk_tree_model_sort_reset_default_sort_func (GtkTreeModelSort x tree_model_sort) 


This resets the default sort function to be in the ’unsorted’ state. 


That is, it is in the same order as the child model. It will re-sort the model to be in the same order as the 
child model only if the GtkTreeModelSort is in ’unsorted’ state. 


Parameters: 


child_model [in] a GtkTreeModel 


Returns: 


void 
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6.57 GtkTreeModelFilter 


6.57.1 Detailed Description 


A GtkTreeModelFilter is a tree model which wraps another tree model, and can do the following things:. 


Filter specific rows, based on data from a "visible column", a column storing booleans indicating whether 
the row should be filtered or not, or based on the return value of a "visible function", which gets a model, 
iter and user_data and returns a boolean indicating whether the row should be filtered or not. 


Modify the "appearance" of the model, using a modify function. This is extremely powerful and allows 
for just changing some values and also for creating a completely different model based on the given child 
model. 


Set a different root node, also known as a "Virtual root". You can pass in a GtkTreePath indicating the root 
node for the filter at construction time. 


Data Structures 


e struct _GtkTreeModelFilter 


GtkTreeModelFilter instance structure. 


¢ struct _GtkTreeModelFilterClass 


GtkTreeModelFilter instance class structure. 


Typedefs 


e typedef gboolean(« GtkTreeModelFilterVisibleFunc )(GtkTreeModel *model, GtkTreelter xiter, 
gpointer data) 


A function which decides whether the row indicated by iter is visible. 


e typedef void(* GtkTreeModelFilterModifyFunc )(GtkTreeModel «model, GtkTreelter xiter, GValue 
«value, gint column, gpointer data) 


A function which calculates display values from raw values in the model. 


Functions 


e GtkTreeModel x gtk_tree_model_filter_new (GtkTreeModel «child_model, GtkTreePath x*root) 


Creates a new GtkTreeModel, with child_model as the child_model and root as the virtual root. 


e void gtk_tree_model_filter_set_visible_func (GtkTreeModelFilter filter, GtkTreeModelFilterVisi- 
bleFunc func, gpointer data, GtkDestroyNotify destroy) 


Sets the visible function used when filtering the filter to be func. 


e void gtk _tree_model_filter_set_modify_func (GtkTreeModelFilter +filter, gint n_columns, GType 
«types, GtkTreeModelFilterModifyFunc func, gpointer data, GtkDestroyNotify destroy) 


With the n_columns and types parameters, you give an array of column types for this model (which will be 
exposed to the parent model/view). 
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void gtk_tree_model_filter_set_visible_column (GtkTreeModelFilter «filter, gint column) 


Sets column of the child_model to be the column where filter should look for visibility information. 


GtkTreeModel x gtk_tree_model_filter_get_model (GtkTreeModelFilter filter) 


Returns a pointer to the child model of filter. 


gboolean gtk_tree_model_filter_convert_child_iter_to_iter (GtkTreeModelFilter +filter, GtkTreelter 
*filter_iter, GtkTreelter *child_iter) 


Sets filter_iter to point to the row in filter that corresponds to the row pointed at by child_iter. 


void gtk_tree_model filter _convert_iter_to_child_iter (GtkTreeModelFilter filter, GtkTreelter 
*child_iter, GtkTreelter «filter_iter) 


Sets child_iter to point to the row pointed to by filter_iter. 


GtkTreePath * gtk_tree_model_filter_convert_child_path_to_path (GtkTreeModelFilter filter, Gtk- 
TreePath *child_path) 


Converts child_path to a path relative to filter. 


GtkTreePath « gtk_tree_model_filter_convert_path_to_child_path (GtkTreeModelFilter filter, Gtk- 
TreePath x*filter_path) 


Converts filter_path to a path on the child model of filter. 


void gtk_tree_model_filter_refilter (GtkTreeModelFilter xfilter) 


Emits row_changed for each row in the child model, which causes the filter to re-evaluate whether a row is 
visible or not. 


void gtk_tree_model_filter_clear_cache (GtkTreeModelFilter «filter) 


This function should almost never be called. 


6.57.2 Typedef Documentation 


6.57.2.1 typedef void(« GtkTreeModelFilterModifyFunc)(GtkTreeModel «model, GtkTreelter 


xiter, GValue «value, gint column, gpointer data) 


A function which calculates display values from raw values in the model. 


It must fill value with the display value for the column column in the row indicated by iter. 


Since this function is called for each data access, it’s not a particularly efficient operation. 


Parameters: 


model [in] the GtkTreeModelFilter 


iter [in] a GtkTreelter pointing to the row whose display values are determined 


value [in] A GValue which is already initialized for with the correct type for the column column. 


column [in] the column whose display value is determined. 


data [in] user data given to gtk_tree_model_filter_set_modify_func() 


Returns: 


void 
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6.57.2.2 typedef gboolean(« GtkTreeModelFilterVisibleFunc)(GtkTreeModel «model, GtkTreelter 
xiter, gpointer data) 


A function which decides whether the row indicated by iter is visible. 


Parameters: 
model [in] the child model of the GtkTreeModelFilter 
iter [in] a GtkTreelter pointing to the row in model whose visibility is determined 


data [in] user data given to gtk_tree_model_filter_set_visible_func() 


Returns: 


Whether the row indicated by iter is visible. 


6.57.3 Function Documentation 


6.57.3.1 void gtk_tree_model filter_clear_cache (GtkTreeModelFilter + filter) 


This function should almost never be called. 

It clears the filter of any cached iterators that haven't been reffed with gtk_tree_model_ref_node(). This 
might be useful if the child model being filtered is static (and doesn’t change often) and there has been a 
lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. 
Parameters: 


filter [in] a GtkTreeModelFilter 


Returns: 


void 


6.57.3.2 gboolean gtk_tree_model_filter_convert_child_iter_to_iter (GtkTreeModelFilter x filter, 
GtkTreelter x filter_iter, GtkTreelter x child_iter) 


Sets filter_iter to point to the row in filter that corresponds to the row pointed at by child_iter. 


If filter_iter was not set, FALSE is returned. 


Parameters: 
filter [in] a GtkTreeModelFilter 
filter_iter [in] An uninitialized GtkTreelter. 


child_iter [in] A valid GtkTreelter pointing to a row on the child model. 


Returns: 


TRUE, if filter_iter was set, i.e. if child_iter is a valid iterator pointing to a visible row in child model. 
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6.57.3.3 GtkTreePathx gtk_tree_model filter_convert_child_path_to_path (GtkTreeModelFilter + 
filter, GtkTreePath x child_path) 


Converts child_path to a path relative to filter. 
That is, child_path points to a path in the child model. The rerturned path will point to the same row in the 
filtered model. If child_path isn't a valid path on the child model or points to a row which is not visible in 
filter, then NULL is returned. 
Parameters: 

filter [in] a GtkTreeModelFilter 

child_path [in] A GtkTreePath to convert. 


Returns: 


A newly allocated GtkTreePath, or NULL. 


6.57.3.4 void gtk_tree_model filter_convert_iter_to_child_iter (GtkTreeModelFilter « filter, 
GtkTreelter x child_iter, GtkTreelter x filter_iter) 


Sets child_iter to point to the row pointed to by filter_iter. 


Parameters: 
filter [in] a GtkTreeModelFilter 
child_iter [in] An uninitialized GtkTreelter. 


filter_iter [in] A valid GtkTreelter pointing to a row on filter. 


Returns: 


void 


6.57.3.5  GtkTreePathx gtk_tree_model filter_convert_path_to_child_path (GtkTreeModelFilter + 
filter, GtkTreePath x filter_path) 


Converts filter_path to a path on the child model of filter. 
That is, filter_path points to a location in filter. The returned path will point to the same location in the 
model not being filtered. If filter_path does not point to a location in the child model, NULL is returned. 
Parameters: 

filter [in] a GtkTreeModelFilter 

filter_path [in] A GtkTreePath to convert. 


Returns: 


A newly allocated GtkTreePath, or NULL. 
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6.57.3.6 GtkTreeModel« gtk_tree_model filter_get_model (GtkTreeModelFilter x filter) 


Returns a pointer to the child model of filter. 


Parameters: 


child_model [in] a GtkTreeModel 


Returns: 


A pointer to a GtkTreeModel. 


6.57.3.7 GtkTreeModelx gtk_tree_model filter_new (GtkTreeModel x child_model, GtkTreePath x 
root) 


Creates a new GtkTreeModel, with child_model as the child_model and root as the virtual root. 


Parameters: 


child_model [in] a GtkTreeModel 
root [in] A GtkTreePath or NULL. 


Returns: 


A new GtkTreeModel. 


6.57.3.8 void gtk_tree_model filter_refilter (GtkTreeModelFilter x filter) 


Emits row_changed for each row in the child model, which causes the filter to re-evaluate whether a row is 
visible or not. 


Parameters: 


filter [in] a GtkTreeModelFilter 


Returns: 


void 


6.57.3.9 void gtk_tree_model filter_set_modify_func (GtkTreeModelFilter x filter, gint n_columns, 
GType + types, GtkTreeModelFilterModifyFunc func, gpointer data, GtkDestroyNotify 
destroy) 


With the n_columns and types parameters, you give an array of column types for this model (which will be 
exposed to the parent model/view). 


The func, data and destroy parameters are for specifying the modify function. The modify function will get 
called for each data access, the goal of the modify function is to return the data which should be displayed 
at the location specified using the parameters of the modify function. 


Parameters: 


filter [in] A GtkTreeModelFilter 
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n_columns [in] The number of columns in the filter model. 
types [in] The GTypes of the columns. 

func [in] A GtkTreeModelFilterModifyFunc 

data [in] User data to pass to the modify function, or NULL. 
destroy [in] Destroy notifier of data, or NULL. 


Returns: 


void 


6.57.3.10 void gtk_tree_model filter_set_visible_column (GtkTreeModelFilter x filter, gint 
column) 


Sets column of the child_model to be the column where filter should look for visibility information. 


columns should be a column of type G_TYPE_BOOLEAN, where TRUE means that a row is visible, and 
FALSE if not. 


Parameters: 


child_model [in] a GtkTreeModel 


column [in] A gint which is the column containing the visible information. 


Returns: 


void 


6.57.3.11 void gtk_tree_model_filter_set_visible_func (GtkTreeModelFilter + filter, 
GtkTreeModelFilterVisibleFunc func, gpointer data, GtkDestroyNotify destroy) 


Sets the visible function used when filtering the filter to be func. 
The function should return TRUE if the given row should be visible and FALSE otherwise. 


If the condition calculated by the function changes over time (e.g. because it depends on some global 
parameters), you must call gtk_tree_model_filter_refilter() to keep the visibility information of the model 
uptodate. 


Parameters: 


filter [in] A GtkTreeModelFilter. 


func [in] A GtkTreeModelFilterVisibleFunc, the visible function. 


data [in] User data to pass to the visible function, or NULL. 
destroy [in] Destroy notifier of data, or NULL. 

Returns: 
void 
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6.58 GtkCellLayout 


6.58.1 Detailed Description 


GtkCellLayout is an interface to be implemented by all objects which want to provide a 
GtkTree ViewColumn-like API for packing cells, setting attributes and data funcs. 


One of the notable features provided by implementations of GtkCellLayout are attributes. Attributes let 
you set the properties in flexible ways. They can just be set to constant values like regular properties. But 
they can also be mapped to a column of the underlying tree model with gtk_cell_layout_set_attributes(), 
which means that the value of the attribute can change from cell to cell as they are rendered by the cell 
renderer. Finally, it is possible to specify a function with gtk_cell_layout_set_cell_data_func() that is called 
to determine the value of the attribute for each cell that is rendered. 


Data Structures 


e struct _GtkCellLayoutlface 


GtkCellLayout interface structure. 


Functions 


void gtk_cell_layout_pack_start (GtkCellLayout *cell_layout, GtkCellRenderer «cell, gboolean ex- 
pand) 


Packs the cell into the beginning of cell_layout. 


void gtk_cell_layout_pack_end (GtkCellLayout *cell_layout, GtkCellRenderer «cell, gboolean ex- 
pand) 


Adds the cell to the end of cell_layout. 


void gtk_cell_layout_clear (GtkCellLayout x*cell_layout) 


Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout. 


void gtk_cell_layout_set_attributes (GtkCellLayout *cell_layout, GtkCellRenderer «cell,...) G_- 
GNUC_NULL_TERMINATED 


Sets the attributes in list as the attributes of cell_layout. 


void gtk cell_layout_add_attribute (GtkCellLayout x*cell_layout, GtkCellRenderer *cell, const 
gchar «attribute, gint column) 


Adds an attribute mapping to the list in cell_layout. 


void gtk_cell_layout_set_cell_data_func (GtkCellLayout *cell_layout, GtkCellRenderer *cell, Gtk- 
CellLayoutDataFunc func, gpointer func_data, GDestroyNotify destroy) 


Sets the GtkCellLayoutDataFunc to use for cell_layout. 


void gtk_cell_layout_clear_attributes (GtkCellLayout *cell_layout, GtkCellRenderer *cell) 


Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). 


void gtk_cell_layout_reorder (GtkCellLayout x*cell_layout, GtkCellRenderer «cell, gint position) 


Re-inserts cell at position. 
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e void gtk_cell_layout_pack_next_line (GtkCellLayout *cell_layout, GtkCellRenderer «cell, gboolean 
expand) 


Pack a GtkCellRenderer in the next line of a GtkCellLayout. 


e void gtk_cell_layout_pack_next_line_start (GtkCellLayout x*cell_layout, GtkCellRenderer xcell, 
gboolean expand) 


Pack a GtkCellRenderer in the next line of a GtkCellLayout, to the start of the left room. 


6.58.2 Function Documentation 


6.58.2.1 void gtk_cell_layout_add_attribute (GtkCellLayout x cell_layout, GtkCellRenderer x cell, 
const gchar * attribute, gint column) 


Adds an attribute mapping to the list in cell_layout. 


The column is the column of the model to get a value from, and the attribute is the parameter on cell to 
be set from the value. So for example if column 2 of the model contains strings, you could have the "text" 
attribute of a GtkCellRendererText get its values from column 2. 


Parameters: 


cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer. 
attribute [in] An attribute on the renderer. 


column [in] The column position on the model to get the attribute from. 


Returns: 


void 


6.58.2.2 void gtk_cell_layout_clear (GtkCellLayout x cell_layout) 
Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout. 


Parameters: 


cell_layout [in] A GtkCellLayout. 


Returns: 


void 


6.58.2.3 void gtk_cell_layout_clear_attributes (GtkCellLayout x cell_layout, GtkCellRenderer * 
cell) 


Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). 


Parameters: 


cell_layout [in] A GtkCellLayout. 
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cell [in] A GtkCellRenderer to clear the attribute mapping on. 


Returns: 


void 


6.58.2.4 void gtk_cell_layout_pack_end (GtkCellLayout x cell_layout, GtkCellRenderer + cell, 
gboolean expand) 


Adds the cell to the end of cell_layout. 


If expand is FALSE, then the cell is allocated no more space than it needs. Any unused space is divided 
evenly between cells for which expand is TRUE. 


Note that reusing the same cell renderer is not supported. 


Parameters: 


cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer. 


expand [in] TRUE if cell is to be given extra space allocated to cell_layout. 


Returns: 


void 


6.58.2.5 void gtk_cell_layout_pack_next_line (GtkCellLayout x cell_layout, GtkCellRenderer + 
cell, gboolean expand) 


Pack a GtkCellRenderer in the next line of a GtkCellLayout. 


This function is normally called by gtk_tree_view_column_pack_end(). 


Parameters: 


cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer. 


expand [in] gboolean, If TRUE, cell is to be given extra space allocated to cell_layout. 


Returns: 


void 


Since 


LIMO RI 


6.58.2.6 void gtk_cell_layout_pack_next_line_start (GtkCellLayout x cell_layout, 
GtkCellRenderer x cell, gboolean expand) 


Pack a GtkCellRenderer in the next line of a GtkCellLayout, to the start of the left room. 
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Parameters: 
cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer. 


expand [in] gboolean, If TRUE, the cell is to be given extra space allocated to cell_layout. 


Returns: 


void 


Since 


LIMO RI 


6.58.2.7 void gtk_cell_layout_pack_start (GtkCellLayout x cell_layout, GtkCellRenderer x cell, 
gboolean expand) 


Packs the cell into the beginning of cell_layout. 


If expand is FALSE, then the cell is allocated no more space than it needs. Any unused space is divided 
evenly between cells for which expand is TRUE. 


Note that reusing the same cell renderer is not supported. 


Parameters: 
cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer. 


expand [in] TRUE if cell is to be given extra space allocated to cell_layout. 


Returns: 


void 


6.58.2.8 void gtk_cell_layout_reorder (GtkCellLayout x cell_layout, GtkCellRenderer x cell, gint 
position) 
Re-inserts cell at position. 


Note that cell has already to be packed into cell_layout for this to function properly. 


Parameters: 
cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer to reorder. 


position [in] New position to insert cell at. 


Returns: 


void 
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6.58.2.9 void gtk_cell_layout_set_attributes (GtkCellLayout « cell_layout, GtkCellRenderer x cell, 
s) 


Sets the attributes in list as the attributes of cell_layout. 


The attributes should be in attribute/column order, as in gtk_cell_layout_add_attribute(). All existing at- 
tributes are removed, and replaced with the new attributes. 


Parameters: 
cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer. 
... [in] A NULL -terminated list of attributes. 


Returns: 


void 


6.58.2.10 void gtk_cell_layout_set_cell_data_func (GtkCellLayout x cell_layout, GtkCellRenderer 
x cell, GtkCellLayoutDataFunc func, gpointer func_data, GDestroyNotify destroy) 


Sets the GtkCellLayoutDataFunc to use for cell_layout. 


This function is used instead of the standard attributes mapping for setting the column value, and should set 
the value of cell_layout's cell renderer(s) as appropriate. func may be NULL to remove and older one. 


Parameters: 
cell_layout [in] A GtkCellLayout. 
cell [in] A GtkCellRenderer. 
func [in] The GtkCellLayoutDataFunc to use. 


func_data [in] The user data for func. 


destroy [in] The destroy notification for func_data. 


Returns: 


void 
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6.59 GtkCellRenderer 


6.59.1 Detailed Description 


The GtkCellRenderer is a base class of a set of objects used for rendering a cell to a GdkDrawable. 


These objects are used primarily by the GtkTreeView widget, though they aren't tied to them in any specific 
way. It is worth noting that GtkCellRenderer is not a GtkWidget and cannot be treated as such. 


The primary use of a GtkCellRenderer is for drawing a certain graphical elements on a GdkDrawable. 
Typically, one cell renderer is used to draw many cells on the screen. To this extent, it isn’t expected that 
a CellRenderer keep any permanent state around. Instead, any state is set just prior to use using GObjects 
property system. Then, the cell is measured using gtk_cell_renderer_get_size(). Finally, the cell is rendered 
in the correct location using gtk_cell_renderer_render(). 


There are a number of rules that must be followed when writing a new GtkCellRenderer. First and formost, 
it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a 
GtkStyle change. The GtkCellRenderer also has a number of generic properties that are expected to be 
honored by all children. 


Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell 
renderer can be activatable like GtkCellRendererToggle, which toggles when it gets activated by a mouse 
click, or it can be editable like GtkCellRendererText, which allows the user to edit the text using a GtkEntry. 
To make a cell renderer activatable or editable, you have to implement the activate or start_editing virtual 
functions, respectively. 


Code Example: 
GtkCellRenderer x*cell; 
GtkTreeViewColumn *column; 


cell = gtk_cell_renderer_text_new (); 
column = gtk_tree_view_column_new_with_attributes ("Node ID", cell, "markup", 0, NULL); 


gtk_tree_view_column_set_sort_column_id (column, 0); 
gtk_tree_view_append_column (GTK_TREE_VIEW (tree_view), column); 


cell = gtk_cell_renderer_text_new (); 


column = gtk_tree_view_column_new_with_attributes ("Random Number", cell, "text", 1, NULL); 


gtk_tree_view_column_set_sort_column_id (column, 1); 
gtk_tree_view_append_column (GTK_TREE_VIEW (tree_view), column); 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkCellRenderer 


GtkCellRenderer instance structure. 


e struct _GtkCellRendererClass 


GTK Native GtkCellRenderer instance class structure. 
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Enumerations 


enum GtkCellRendererPixCellState { , GTK_CELL_RENDERER_PIXBUF_SHRINK = 1, GTK_- 
CELL_RENDERER_PIXBUF_EXPAND = 2, GTK_CELL_RENDERER_PIXBUF_ZOOM = 3, 
GTK_CELL_RENDERER_PIXBUF_NULL = 4 } 


Functions 


void gtk_cell_renderer_get_size (GtkCellRenderer «cell, GtkWidget «widget, GdkRectangle «cell_- 
area, gint *x_offset, gint *y_offset, gint «width, gint *height) 


Obtains the width and height needed to render the cell. 


void gtk_cell_renderer_render (GtkCellRenderer «cell, GdkWindow «window, GtkWidget «widget, 
GdkRectangle *background_area, GdkRectangle *cell_area, GdkRectangle *expose_area, GtkCell- 
RendererState flags) 


Invokes the virtual render function of the GtkCellRenderer. 


gboolean gtk_cell_renderer_activate (GtkCellRenderer cell, GdkEvent x*event, GtkWidget *widget, 
const gchar «path, GdkRectangle *background_area, GdkRectangle *cell_area, GtkCellRender- 
erState flags) 


Passes an activate event to the cell renderer for possible processing. 


GtkCellEditable * gtk_cell_renderer_start_editing (GtkCellRenderer «cell, GdkEvent *event, Gtk- 
Widget «widget, const gchar xpath, GdkRectangle *background_area, GdkRectangle *cell_area, 
GtkCellRendererState flags) 


Passes an activate event to the cell renderer for possible processing. 


void gtk_cell_renderer_set_fixed_size (GtkCellRenderer «cell, gint width, gint height) 


Sets the renderer size to be explicit, independent of the properties set. 


void gtk_cell_renderer_get_fixed_size (GtkCellRenderer xcell, gint «width, gint height) 


Fills in width and height with the appropriate size of cell. 


void gtk_cell_renderer_set_cell_flag (GtkCellRenderer «cell, GtkWidget «widget, GtkCellRender- 
erType flag) 


Set the flag of a GtkCellRenderer. 


void gtk_cell_renderer_set_cell_font_size (GtkCellRenderer «cell, GtkCellRendererType flag, guint 
size) 


Set the font size of a GtkCellRenderer. 


void gtk_cell_renderer_set_render_scale (GtkCellRenderer «cell, gint needscale, double scale) 


Set the start drawing position of a GtkCellRenderer when drawing the rectangle. 


void gtk_cell_renderer_stop_editing (GtkCellRenderer *cell, gboolean canceled) 


Informs the cell renderer that the editing is stopped. 
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6.59.2 Enumeration Type Documentation 


6.59.2.1 enum GtkCellRendererPixCellState 


Enumerator: 


GTK_CELL_RENDERER_PIXBUF_SHRINK Normal. 


GTK_CELL_RENDERER_PIXBUF_EXPAND shrink pixbuf,only when pixbuf size greater then 
cell size 


GTK_CELL_RENDERER_PIXBUF_ZOOM expand pixbuf when pixbuf size < cell size 


GTK_CELL_RENDERER_PIXBUF_NULL shrink and expand ,it will scale pixbuf to draw in cell 
size 


6.59.3 Function Documentation 


6.59.3.1 gboolean gtk_cell_renderer_activate (GtkCellRenderer x cell, GdkEvent « event, 
GtkWidget x widget, const gchar « path, GdkRectangle « background_area, GdkRectangle 
x cell_area, GtkCellRendererState flags) 


Passes an activate event to the cell renderer for possible processing. 


Some cell renderers may use events; for example, GtkCellRendererToggle toggles when it gets a mouse 
click. 


Parameters: 


cell [in] a GtkCellRenderer 

event [in] a GdkDrawable to draw to 

widget [in] widget that received the event 

path [in] widget-dependent string representation of the event location; 
background_area [in] background area as passed to gtk_cell_renderer_render 
cell_area [in] cell area as passed to gtk_cell_renderer_render 


flags [in] render flags 


Returns: 


TRUE if the event was consumed/handled 


6.59.3.2 void gtk_cell_renderer_get_fixed_size (GtkCellRenderer x cell, gint x width, gint « height) 
Fills in width and height with the appropriate size of cell. 


Parameters: 


cell [in] a GtkCellRenderer 
width [out] location to fill in with the fixed width of the widget, or NULL 
height [out] location to fill in with the fixed height of the widget, or NULL 


Returns: 


void 
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6.59.3.3 void gtk_cell_renderer_get_size (GtkCellRenderer x cell, GtkWidget x widget, 
GdkRectangle + cell_area, gint « x_offset, gint x y_offset, gint x width, gint x height) 


Obtains the width and height needed to render the cell. 


Used by view widgets to determine the appropriate size for the cell_area passed to gtk_cell_renderer_- 
render(). If cell_area is not NULL, fills in the x and y offsets (if set) of the cell relative to this location. 
Please note that the values set in width and height, as well as those in x_offset and y_offset are inclusive of 
the xpad and ypad properties. 


Parameters: 
cell [in] a GtkCellRenderer 
widget [in] the widget the renderer is rendering to 
cell_area [in] The area a cell will be allocated, or NULL 
x_offset [out] location to return x offset of cell relative to cell_area, or NULL 
y_offset [out] location to return y offset of cell relative to cell_area, or NULL 
width [out] location to return width needed to render a cell, or NULL 


height [out] location to return height needed to render a cell, or NULL 


Returns: 


void 


6.59.3.4 void gtk_cell_renderer_render (GtkCellRenderer + cell, GdkWindow x window, 
GtkWidget « widget, GdkRectangle « background_area, GdkRectangle x cell_area, 
GdkRectangle x expose_area, GtkCellRendererState flags) 


Invokes the virtual render function of the GtkCellRenderer. 


The three passed-in rectangles are areas of window. Most renderers will draw within cell_area; the 
xalign, yalign, xpad, and ypad fields of the GtkCellRenderer should be honored with respect to cell_- 
area. background_area includes the blank space around the cell, and also the area containing the tree 
expander; so the background_area rectangles for all cells tile to cover the entire window. expose_area is a 
clip rectangle. 


Parameters: 
cell [in] a GtkCellRenderer 
window [in] a GdkDrawable to draw to 
widget [in] The widget owning window 
background_areas [in] entire cell area (including tree expanders and maybe padding on the sides) 
cell_area [in] area normally rendered by a cell renderer 
expose_area [in] area that actually needs updating 


flags [in] flags that affect rendering 


Returns: 


void 
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6.59.3.5 void gtk_cell_renderer_set_cell_flag (GtkCellRenderer x cell, GtkWidget * widget, 
GtkCellRendererType flag) 


Set the flag of a GtkCellRenderer. 


Parameters: 
cell [in] A GtkCellRenderer. 
widget [in] A GtkWidget. 
flag [in] A type of GtkCellRendererType. 


Since 


LIMO R1 


6.59.3.6 void gtk_cell_renderer_set_cell_font_size (GtkCellRenderer x cell, GtkCellRendererType 
flag, guint size) 


Set the font size of a GtkCellRenderer. 


Parameters: 
cell [in] A GtkCellRenderer. 
flag [in] The GtkCellRendererType. 


size [in] The font size tobe set. 


Since 


LIMO R1 


6.59.3.7 void gtk_cell_renderer_set_fixed_size (GtkCellRenderer x cell, gint width, gint height) 


Sets the renderer size to be explicit, independent of the properties set. 


Parameters: 
cell [in] a GtkCellRenderer 
width [in] the width of the cell renderer, or -1 


height [in] the height of the cell renderer, or -1 


Returns: 


void 


6.59.3.8 void gtk_cell_renderer_set_render_scale (GtkCellRenderer x cell, gint needscale, double 
scale) 


Set the start drawing position of a GtkCellRenderer when drawing the rectangle. 
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Parameters: 
cell [in] A GtkCellRenderer. 
needscale [in] If TRUE, the GtkCellRenderer needs scaling. 


scale [in] The adjustment of the drawing in the cell. 


Since 


LIMO R1 


Returns: 


void 


6.59.3.9 GtkCellEditablex gtk_cell_renderer_start_editing (GtkCellRenderer x cell, GdkEvent x 
event, GtkWidget x widget, const gchar x path, GdkRectangle x background_area, 
GdkRectangle « cell_area, GtkCellRendererState flags) 


Passes an activate event to the cell renderer for possible processing. 


Parameters: 
cell [in] a GtkCellRenderer 
event [in] a GdkDrawable to draw to 
widget [in] widget that received the event 
path [in] widget-dependent string representation of the event location 
background_area [in] background area as passed to gtk_cell_renderer_render 
cell_area [in] cell area as passed to gtk_cell_renderer_render 


flags [in] render flags 


Returns: 


TRUE if the event was consumed/handled 


6.59.3.10 void gtk_cell_renderer_stop_editing (GtkCellRenderer « cell, gboolean canceled) 


Informs the cell renderer that the editing is stopped. 

If canceled is TRUE, the cell renderer will emit the "editing-canceled" signal. This function should be 
called by cell renderer implementations in response to the "editing-done" signal of GtkCellEditable. 
Parameters: 


cell [in] A GtkCellRenderer. 
canceled [in] TRUE if the editing has been canceled 


Returns: 


void 
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6.60 GtkCellEditable 


6.60.1 Detailed Description 


The GtkCellEditable interface must be implemented for widgets to be usable when editing the contents of 
a GtkTreeView cell. 


Functions 


e void gtk_cell_editable_start_editing (GtkCellEditable *cell_editable, GdkEvent xevent) 


Begins editing on a cell_editable. 


e void gtk_cell_editable_editing done (GtkCellEditable *cell_editable) 


Emits the "editing_done" signal. 


e void gtk_cell_editable_remove_widget (GtkCellEditable *cell_editable) 


Emits the "remove_widget" signal. 


6.60.2 Function Documentation 
6.60.2.1 void gtk_cell_editable_editing_done (GtkCellEditable + cell_editable) 


Emits the "editing_done" signal. 


This signal is a sign for the cell renderer to update its value from the cell. 


Parameters: 


cell_editable [in] a GtkCellEditable 


Returns: 


void 


6.60.2.2 void gtk_cell_editable_remove_widget (GtkCellEditable x cell_editable) 


Emits the "remove_widget" signal. 


This signal is meant to indicate that the cell is finished editing, and the widget may now be destroyed. 


Parameters: 


cell_editable [in] a GtkCellEditable 


Returns: 


void 
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6.60.2.3 void gtk_cell editable_start_editing (GtkCellEditable x cell_editable, GdkEvent x event) 


Begins editing on a cell_editable. 

event is the GdkEvent that began the editing process. It may be NULL, in the instance that editing was 
initiated through programatic means. 

Parameters: 


cell_editable [in] a GtkCellEditable 
event [in] A GdkEvent, or NULL 


Returns: 


void 
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6.61 GtkCellRendererPixbuf 


6.61.1 Detailed Description 


A GtkCellRendererPixbuf can be used to render an image in a cell. 
It allows to render either a given GdkPixbuf (set via the pixbuf property) or a stock icon (set via the stock-id 
property). 


To support the tree view, GtkCellRendererPixbuf also supports rendering two alternative pixbufs, when the 
is-expander property is TRUE. If the is-expanded property is TRUE and the pixbuf-expander-open property 
is set to a pixbuf, it renders that pixbuf, if the is-expanded property is FALSE and the pixbuf-expander- 
closed property is set to a pixbuf, it renders that one. 


Modified for 
LIMO RI 


modified log: funtions added: why: scale small image to big funtion where: void gtk_cell_renderer_- 
pixbuf_set_scale_sb (GtkCellRendererPixbuf x*cellpixbuf,guint scale); guint gtk_cell_renderer_pixbuf_- 
get_scale_sb (GtkCellRendererPixbuf «cellpixbuf); author:zyongliang 


Data Structures 


e struct _GtkCellRendererPixbuf 


GtkCellRendererPixbuf instance structure. 


e struct _GtkCellRendererPixbufClass 


GTK Native GtkCellRendererPixbuf instance class structure. 


Functions 


e GtkCellRenderer * gtk_cell_renderer_pixbuf_new (void) 


Creates a new GtkCellRendererPixbuf. 


e void gtk_cell_renderer_pixbuf_set_is_scale (GtkCellRendererPixbuf *cellpixbuf, gint scale) 


Set the scale property of a GtkCellRendererPixbuf. 


e gint gtk_cell_renderer_pixbuf_get_is_scale (GtkCellRendererPixbuf *cellpixbuf) 


Get the scale property of a GtkCellRendererPixbuf. 


e void gtk_cell_renderer_pixbuf_set_scale_sb (GtkCellRendererPixbuf «cellpixbuf, guint scale) 


Set the property of a GtkCellRendererPixbuf in automatic scaling to full size when is too small. 


e guint gtk_cell_renderer_pixbuf_get_scale_sb (GtkCellRendererPixbuf *cellpixbuf) 


Get the property of a GtkCellRendererPixbuf in automatic scaling to full size when is too small. 
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6.61.2 Function Documentation 
6.61.2.1 gint gtk_cell_renderer_pixbuf get_is_scale (GtkCellRendererPixbuf x cellpixbuf) 


Get the scale property of a GtkCellRendererPixbuf. 


Parameters: 


cellpixbuf [in] A GtkCellRendererPixbuf. 


Returns: 


The scale property of the cellpixbuf, guint scale {0,1} 


Since 


LIMO R1 


6.61.2.2 guint gtk_cell_renderer_pixbuf_get_scale_sb (GtkCellRendererPixbuf x cellpixbuf) 


Get the property of a GtkCellRendererPixbuf in automatic scaling to full size when is too small. 


Parameters: 


cellpixbuf [in] A GtkCellRendererPixbuf. 


Since 


LIMO RI 


6.61.2.3 GtkCellRendererx gtk_cell_renderer_pixbuf_new (void) 


Creates a new GtkCellRendererPixbuf. 


Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_- 
set()). Also, with GtkTreeViewColumn, you can bind a property to a value in a GtkTreeModel. For 
example, you can bind the "pixbuf" property on the cell renderer to a pixbuf value in the model, thus 
rendering a different image in each row of the GtkTree View. 


Returns: 


the new cell renderer 


6.61.2.4 void gtk_cell_renderer_pixbuf_set_is_scale (GtkCellRendererPixbuf x cellpixbuf, gint 
scale) 


Set the scale property of a GtkCellRendererPixbuf. 


Parameters: 

cellpixbuf [in] A GtkCellRendererPixbuf. 

scale [in] TRUE if the cellpixbuf is scalable, guint scale {0,1} 
Since 


LIMO R1 
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6.61.2.5 void gtk_cell_renderer_pixbuf_set_scale_sb (GtkCellRendererPixbuf x cellpixbuf, guint 
scale) 


Set the property of a GtkCellRendererPixbuf in automatic scaling to full size when is too small. 


Parameters: 
cellpixbuf [in] A GtkCellRendererPixbuf. 
scale [in] TRUE if the cellpixbuf is scalable. 


Since 


LIMO RI 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


606 Module Documentation 


6.62 GtkCellRendererProgress 


6.62.1 Detailed Description 


GtkCellRendererProgress renders a numeric value as a progress par in a cell. 


Additionally, it can display a text on top of the progress bar. 


Data Structures 


e struct _GtkCellRendererProgress 


GtkCellRendererProgress instance structure. 


e struct _GtkCellRendererProgressClass 


GtkCellRendererProgress instance class structure. 


Functions 


e GtkCellRenderer * gtk_cell_renderer_progress_new (void) 


Creates a new GtkCellRendererProgress. 


6.62.2 Function Documentation 
6.62.2.1 GtkCellRendererx gtk_cell_renderer_progress_new (void) 
Creates a new GtkCellRendererProgress. 


Returns: 


the new cell renderer 
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6.63 GtkCellRendererText 


6.63.1 Detailed Description 


A GtkCellRendererText renders a given text in its cell, using the font, color and style information provided 
by its properties. 


The text will be ellipsized if it is too long and the ellipsize property allows it. 


If the mode is GTK_CELL_RENDERER_MODE_EDITABLE, the GtkCellRendererText allows to edit its 
text using an entry. 


Data Structures 


struct _GtkCellRendererText 


GtkCellRendererText instance structure. 


struct _GtkCellRendererTextClass 


GTK Native GtkCellRendererText instance class structure. 


Functions 


GtkCellRenderer * gtk_cell_renderer_text_new (void) 


Creates a new GtkCellRendererText. 


void gtk_cell_renderer_text_set_fixed_height_from_ font (GtkCellRendererText *renderer, gint 
number_of rows) 


Sets the height of a renderer to explicitly be determined by the "font" and "y_pad" property set on it. 


PangoLayout * gtk_cell_renderer_text_create_layout (GtkCellRendererText *cell, GdkDrawable 
*window, GtkWidget «widget, GdkRectangle x*cell_area, GtkCellRendererState flags, gint «x_offset, 
gint *y_offset) 


Create a PangoLayout from a GtkCellRendererText. 


void gtk_cell_renderer_text_set_slider (GtkCellRendererText «cell, guint flags) 


Set flag of a GtkCellRendererText that the text can slide or not. 


guint gtk _cell_renderer_text_get_is_slider (GtkCellRendererText *cell) 


Get flag of a GtkCellRendererText that the text can slide or not. 


6.63.2 Function Documentation 


6.63.2.1 PangoLayout« gtk_cell_renderer_text_create_layout (GtkCellRendererText + 


cell, GdkDrawable x window, GtkWidget « widget, GdkRectangle x cell_area, 
GtkCellRendererState flags, gint « x_offset, gint x y_offset) 


Create a PangoLayout from a GtkCellRendererText. 
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Parameters: 


cell [in] A GtkCellRendererText. 

window [in] A GdkDrawable. 

widget [in] A GtkWidget that the PangoLayout is created from. 
cell_area [in] The rectangle area of the cell. 

flags [in] The flag of the cell. 

x_offset [out] The x offset of the PangoLayout in the cell. 
y_offset [out] The y offset of the PangoLayout in the cell. 


Returns: 


The created PangoLayout. 


Since 


LIMO R1 


6.63.2.2 guint gtk cell _renderer_text_get_is slider (GtkCellRendererText x cell) 
Get flag of a GtkCellRendererText that the text can slide or not. 


Parameters: 


cell [in] A GtkCellRendererText. 


Returns: 


The slide flag. 


Since 


LIMO R1 


6.63.2.3 GtkCellRenderer* gtk_cell_renderer_text_new (void) 


Creates a new GtkCellRendererText. 


Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_- 
set()). Also, with GtkTreeViewColumn, you can bind a property to a value in a GtkTreeModel. For 
example, you can bind the "text" property on the cell renderer to a string value in the model, thus rendering 
a different string in each row of the GtkTree View 


Returns: 


the new cell renderer 


6.63.2.4 void gtk_cell_renderer_text_set_fixed_height_from_font (GtkCellRendererText x 
renderer, gint number_of_rows) 


Sets the height of a renderer to explicitly be determined by the "font" and "y_pad" property set on it. 
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Further changes in these properties do not affect the height, so they must be accompanied by a subsequent 
call to this function. Using this function is unflexible, and should really only be used if calculating the 
size of a cell is too slow (ie, a massive number of cells displayed). If number_of_rows is -1, then the fixed 
height is unset, and the height is determined by the properties again. 


Parameters: 


renderer [in] A GtkCellRenderer. 


number_of_rows [in] Number of rows of text each cell renderer is allocated, or -1 


Returns: 


void 


6.63.2.5 void gtk_cell_renderer_text_set_slider (GtkCellRendererText x cell, guint flags) 


Set flag of a GtkCellRendererText that the text can slide or not. 


Parameters: 
cell [in] A GtkCellRendererText. 
flags [in] If TRUE, the text of the cell can slide. 


Since 


LIMO R1 
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6.64 GtkCellRendererToggle 


6.64.1 Detailed Description 


GtkCellRendererToggle renders a toggle button in a cell. 


The button is drawn as a radio- or checkbutton, depending on the radio property. When activated, it emits 
the toggled signal. 
Data Structures 


e struct _GtkCellRendererToggle 


GtkCellRendererToggle instance structure. 


e struct _GtkCellRendererToggleClass 


GtkCellRendererToggle instance class structure. 


Functions 


e GtkCellRenderer * gtk_cell_renderer_toggle_new (void) 


Creates a new GtkCellRendererToggle. 


e gboolean gtk_cell_renderer_toggle_get_radio (GtkCellRendererToggle *toggle) 


Returns whether we’re rendering radio toggles rather than checkboxes. 


e void gtk_cell_renderer_toggle_set_radio (GtkCellRendererToggle «toggle, gboolean radio) 


If radio is TRUE, the cell renderer renders a radio toggle (i.e. 


e gboolean gtk_cell_renderer_toggle_get_active (GtkCellRendererToggle *toggle) 


Returns whether the cell renderer is active. 


e void gtk_cell_renderer_toggle_set_active (GtkCellRendererToggle «toggle, gboolean setting) 


Activates or deactivates a cell renderer. 


6.64.2 Function Documentation 
6.64.2.1 gboolean gtk_cell_renderer_toggle_get_active (GtkCellRendererToggle x toggle) 


Returns whether the cell renderer is active. 


See gtk_cell_renderer_toggle_set_active(). 


Parameters: 


toggle [in] a GtkCellRendererToggle 


Returns: 


TRUE if the cell renderer is active 
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6.64.2.2 gboolean gtk_cell_renderer_toggle_get_radio (GtkCellRendererToggle x toggle) 
Returns whether we're rendering radio toggles rather than checkboxes. 


Parameters: 


toggle [in] a GtkCellRendererToggle 


Returns: 


TRUE if we're rendering radio toggles rather than checkboxes 


6.64.2.3 GtkCellRenderer* gtk_cell_renderer_toggle_new (void) 


Creates a new GtkCellRendererToggle. 


Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_- 
set()). Also, with GtkTreeViewColumn, you can bind a property to a value in a GtkTreeModel. For 
example, you can bind the "active" property on the cell renderer to a boolean value in the model, thus 
causing the check button to reflect the state of the model. 


Returns: 


the new cell renderer 


6.64.2.4 void gtk_cell_renderer_toggle_set_active (GtkCellRendererToggle « toggle, gboolean 
setting) 


Activates or deactivates a cell renderer. 


Parameters: 


toggle [in] a GtkCellRendererToggle 


setting [in] the value to set. 


Returns: 


void 


6.64.2.5 void gtk_cell_renderer_toggle_set_radio (GtkCellRendererToggle « toggle, gboolean 
radio) 


If radio is TRUE, the cell renderer renders a radio toggle (i.e. 


a toggle in a group of mutually-exclusive toggles). If FALSE, it renders a check toggle (a standalone 
boolean option). This can be set globally for the cell renderer, or changed just before rendering each cell in 
the model (for GtkTreeView, you set up a per-row setting using GtkTree ViewColumn to associate model 
columns with cell renderer properties). 


Parameters: 


toggle [in] a GtkCellRendererToggle 
radio [in] TRUE to make the toggle look like a radio button 
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Returns: 


void 
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6.65 GtkListStore 


6.65.1 Detailed Description 


The GtkListStore object is a list model for use with a GtkTreeView widget. 


It implements the GtkTreeModel interface, and consequentialy, can use all of the methods available there. 
It also implements the GtkTreeSortable interface so it can be sorted by the view. Finally, 1t also implements 
the tree drag and drop interfaces. 


The GtkListStore can accept most GObject types as a column type, though it can’t accept all custom types. 
Internally, it will keep a copy of data passed in (such as a string or a boxed pointer). Columns that accept 
GObjects are handled a little differently. The GtkListStore will keep a reference to the object instead of 
copying the value. As a result, 1f the object is modified, it is up to the application writer to call gtk_tree_- 
model_row_changed to emit the "row_changed" signal. This most commonly affects lists with GdkPixbufs 
stored. 


Example: Creating a simple list store 


enum { 
COLUMN_STRING, 
COLUMN_INT, 
COLUMN_BOOLEAN, 
N_COLUMNS 

y; 


{ 

GtkListStore *xlist_store; 
GtkTreePath *path; 
GtkTreeIter iter; 

gint i; 


list_store = gtk_list_store_new (N_COLUMNS, 
G_TYPE_STRING, 
G_TYPE_INT, 
G_TYPE_BOOLEAN) ; 


for (i = 0; i < 10; itt) 
gchar xsome_data; 
some_data = get_some_data (i); 


// Add a new row to the model 
gtk_list_store_append (list_store, &iter); 
gtk_list_store_set (list_store, éiter, 

COLUMN_STRING, some_data, 
COLUMN_INT, i, 
COLUMN_BOOLEAN, FALSE, 
>T); 


// As the store will keep a copy of the string internally, 
// we free some_data. 


g_free (some_data); 
} 

// Modify a particular row 

path = gtk_tree_path_new_from_string ("4"); 

gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store), 
&iter, 
path); 

gtk_tree_path_free (path); 

gtk_list_store_set (list_store, €&iter, 

COLUMN_BOOLEAN, TRUE, 
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-1); 


Performance Considerations 


Internally, the GtkListStore was implemented with a linked list with a tail pointer prior to GTK+ 2.6. As a 
result, it was fast at data insertion and deletion, and not fast at random data access. The GtkListStore sets 
the GTK_TREE_MODEL_ITERS_PERSIST flag, which means that GtkTreelters can be cached while the 
row exists. Thus, if access to a particular row is needed often and your code is expected to run on older 
versions of GTK+, it is worth keeping the iter around. 


Atomic Operations 


It is important to note that only the methods gtk_list_store_insert_with_values and gtk_list_store_insert_- 
with_valuesv are atomic, in the sense that the row is being appended to the store and the values filled in 
in a single operation with regard to GtkTreeModel signaling. In contrast, using e.g. gtk_list_store_append 
and then gtk_list_store_set will first create a row, which triggers the "row_inserted" GtkTreeModel signal 
on GtkListStore. The row, however, is still empty, and any signal handler connecting to "row_inserted" on 
this particular store should be prepared for the situation that the row might be empty. This is especially 
important if you are wrapping the GtkListStore inside a GtkTreeModelFilter and are using a GtkTreeMod- 
elFilterVisibleFunc. Using any of the non-atomic operations to append rows to the GtkListStore will cause 
the GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared 
for that. 


Data Structures 


e struct _GtkListStore 


GtkListStore instance structure. 


e struct _GtkListStoreClass 


GtkListStore instance class structure. 


Functions 


GtkListStore x gtk_list_store_new (gint n_columns....) 


Creates a new list store as with n_columns columns each of the types passed in. 


e GtkListStore * gtk_list_store_newv (gint n_columns, GType *types) 


Non-vararg creation function. 


e void gtk_list_store_set_column_types (GtkListStore *list_store, gint n_columns, GType types) 


This function is meant primarily for GObjects that inherit from GtkListStore, and should only be used when 
constructing a new GtkListStore. 


e void gtk list_store_set_value (GtkListStore +list_store, GtkTreelter xiter, gint column, GValue 
*value) 


Sets the data in the cell specified by iter and column. 


e void gtk_list_store_set (GtkListStore x*list_store, GtkTreelter xiter,...) 


Sets the value of one or more cells in the row referenced by iter. 
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e void gtk_list_store_set_valist (GtkListStore x*list_store, GtkTreelter xiter, va_list var_args) 


See gtk_list_store_set(); this version takes a va_list for use by language bindings. 


e gboolean gtk_list_store_remove (GtkListStore *list_store, GtkTreelter xiter) 


Removes the given row from the list store. 


e void gtk_list_store_insert (GtkListStore *list_store, GtkTreelter xiter, gint position) 


Creates a new row at position. 


e void gtk_list_store_insert_before (GtkListStore xlist_store, GtkTreelter xiter, GtkTreelter 
*sibling) 


Inserts a new row before sibling. 


e void gtk_list_store_insert_after (GtkListStore x*list_store, GtkTreelter xiter, GtkTreelter *sibling) 


Inserts a new row after sibling. 


e void gtk_list_store_insert_with_values (GtkListStore x*list_store, GtkTreelter iter, gint posi- 
tion,...) 


Creates a new row at position. 


e void gtk_list_store_insert_with_valuesv (GtkListStore x*list_store, GtkTreelter xiter, gint position, 
gint «columns, GValue «values, gint n_values) 


A variant of gtk_list_store_insert_with_values() which takes the columns and values as two arrays, instead 
of varargs. 


e void gtk_list_store_prepend (GtkListStore x*list_store, GtkTreelter xiter) 


Prepends a new row to list_store. 


e void gtk_list_store_append (GtkListStore *list_store, GtkTreelter xiter) 


Appends a new row to list_store. 


e void gtk_list_store_clear (GtkListStore x*list_store) 


Removes all rows from the list store. 


e gboolean gtk_list_store_iter_is_valid (GtkListStore *list_store, GtkTreelter xiter) 


This function is slow. 


e void gtk_list_store_reorder (GtkListStore *store, gint *new_order) 


Reorders store to follow the order indicated by new_order. 


e void gtk_list_store_swap (GtkListStore «store, GtkTreelter xa, GtkTreelter xb) 


Swaps a and b in store. 


e void gtk_list_store_move_after (GtkListStore «store, GtkTreelter xiter, GtkTreelter position) 


Moves iter in store to the position after position. 


e void gtk_list_store_move_before (GtkListStore «store, GtkTreelter xiter, GtkTreelter *position) 


Moves iter in store to the position before position. 
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6.65.2 Function Documentation 
6.65.2.1 void gtk_list_store_append (GtkListStore x list_store, GtkTreelter x iter) 


Appends a new row to list_store. 

iter will be changed to point to this new row. The row will be empty after this function is called. To fill in 
values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). 

Parameters: 


— list_store : A GtkListStore 


— iter : An unset GtkTreelter to set to the appended row 


Returns: 


void 


6.65.2.2 void gtk_list_store_clear (GtkListStore ~ list_store) 
Removes all rows from the list store. 


Parameters: 


— list_store : A GtkListStore 


Returns: 


void 


6.65.2.3 void gtk_list_store_insert (GtkListStore x list_store, GtkTreelter x iter, gint position) 


Creates a new row at position. 
iter will be changed to point to this new row. If position is larger than the number of rows on the list, then 
the new row will be appended to the list. The row will be empty after this function is called. To fill in 
values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). 
Parameters: 

< list_store : A GtkListStore 

— iter : An unset GtkTreelter to set to the new row 


< position : position to insert the new row 


Returns: 


void 


6.65.2.4 void gtk_list_store_insert_after (GtkListStore  list_store, GtkTreelter x iter, GtkTreelter 
x sibling) 


Inserts a new row after sibling. 
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If sibling is NULL, then the row will be prepended to the beginning of the list. iter will be changed to 
point to this new row. The row will be empty after this function is called. To fill in values, you need to call 
gtk_list_store_set() or gtk_list_store_set_value(). 

Parameters: 


— list_store : A GtkListStore 
< iter : An unset GtkTreelter to set to the new row 
— sibling : A valid GtkTreelter, or NULL 


Returns: 


void 


6.65.2.5 void gtk_list_store_insert_before (GtkListStore x list_store, GtkTreelter x iter, 
GtkTreelter x sibling) 

Inserts a new row before sibling. 

If sibling is NULL, then the row will be appended to the end of the list. iter will be changed to point 

to this new row. The row will be empty after this function is called. To fill in values, you need to call 

gtk_list_store_set() or gtk_list_store_set_value(). 

Parameters: 


< list_store : A GtkListStore 
< iter : An unset GtkTreelter to set to the new row 
< sibling : A valid GtkTreelter, or NULL 


Returns: 


void 


6.65.2.6 void gtk_list_store_insert_with_values (GtkListStore x list_store, GtkTreelter ~ iter, gint 
position, ...) 


Creates a new row at position. 


iter will be changed to point to this new row. If position is larger than the number of rows on the list, then 
the new row will be appended to the list. The row will be filled with the values given to this function. 
Calling gtk_list_store_insert_with_values(list_store, iter, position...) has the same effect as calling 


gtk_list_store_insert (list_store, iter, position); 
gtk_list_store_set (list_store_iter, ...); 


with the difference that the former will only emit a row_inserted signal, while the latter will emit row_- 
inserted, row_changed and, if the list store is sorted, rows_reordered. Since emitting the rows_reordered 
signal repeatedly can affect the performance of the program, gtk_list_store_insert_with_values() should 
generally be preferred when inserting rows in a sorted list store. 


Parameters: 


«+ list_store : A GtkListStore 
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< iter : An unset GtkTreelter to set to the new row, or NULL. 
< position : position to insert the new row 


<—... : pairs of column number and value, terminated with -1 


Returns: 


void 


6.65.2.7 void gtk_list_store_insert_with_valuesv (GtkListStore « list_store, GtkTreelter « iter, gint 
position, gint x columns, GValue * values, gint n_values) 


A variant of gtk_list_store_insert_with_values() which takes the columns and values as two arrays, instead 
of varargs. 


This function is mainly intended for language-bindings. 


Parameters: 
— list_store : A GtkListStore 
< iter : An unset GtkTreelter to set to the new row, or NULL. 
< position : position to insert the new row 
— columns : an array of column numbers 
— values : an array of GValues 


— n_values : the length of the columns and values arrays 


Returns: 


void 


6.65.2.8 gboolean gtk_list_store_iter_is valid (GtkListStore « list_store, GtkTreelter x iter) 


This function is slow. 


Only use it for debugging and/or testing purposes.Checks if the given iter is a valid iter for this GtkList- 
Store. 


Parameters: 
< list_store : A GtkListStore 
< iter : A GtkTreelter. 
Returns: 


TRUE if the iter is valid, FALSE if the iter is invalid. 


6.65.2.9 void gtk_list_store_move_after (GtkListStore + store, GtkTreelter x iter, GtkTreelter x 
position) 


Moves iter in store to the position after position. 


Note that this function only works with unsorted stores. If position is NULL, iter will be moved to the start 
of the list. 
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Parameters: 


— list_store : A GtkListStore 
— types : A GtkTreelter. 
— position : A GtkTreelter or NULL. 


Returns: 


void 


6.65.2.10 void gtk_list_store_move_before (GtkListStore x store, GtkTreelter x iter, GtkTreelter x 
position) 


Moves iter in store to the position before position. 


Note that this function only works with unsorted stores. If position is NULL, iter will be moved to the end 
of the list. 


Parameters: 


— list_store : A GtkListStore 
— iter : A GtkTreelter. 
— position : A GtkTreelter, or NULL. 


Returns: 


void 


6.65.2.11 GtkListStorex gtk_list_store_new (gint n_columns, ...) 


Creates a new list store as with n_columns columns each of the types passed in. 


Note that only types derived from standard GObject fundamental types are supported. As an example, gtk_- 
tree_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_PIXBUFP); will create a new GtkList- 
Store with three columns, of type int, string and GdkPixbuf respectively. 


Parameters: 


— n_columns : number of columns in the list store 


— ... : all GType types for the columns, from first to last 


Returns: 


a new GtkListStore 


6.65.2.12  GtkListStorex gtk_list_store_newv (gint n_columns, GType + types) 


Non-vararg creation function. 


Used primarily by language bindings. 


Parameters: 


— n_columns : number of columns in the list store 
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— types : an array of GType types for the columns, from first to last 


Returns: 


a new GtkListStore 


6.65.2.13 void gtk_list_store_prepend (GtkListStore + list_store, GtkTreelter x iter) 


Prepends a new row to list_store. 

iter will be changed to point to this new row. The row will be empty after this function is called. To fill in 
values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). 

Parameters: 


— list_store : A GtkListStore 


— iter : An unset GtkTreelter to set to the prepend row 


Returns: 


void 


6.65.2.14 gboolean gtk_list_store_remove (GtkListStore « list_store, GtkTreelter x iter) 


Removes the given row from the list store. 

After being removed, iter is set to be the next valid row, or invalidated if it pointed to the last row in 
list_store. 

Parameters: 


— list_store : A GtkListStore 
< iter : A valid GtkTreelter 


Returns: 


TRUE if iter is valid, FALSE if not. 


6.65.2.15 void gtk_list_store_reorder (GtkListStore « store, gint * new_order) 


Reorders store to follow the order indicated by new_order. 


Note that this function only works with unsorted stores. 


Parameters: 


— list_store : A GtkListStore 


— new_order : an array of integers mapping the new position of each child to its old position before 
the re-ordering, i.e. new_order[newpos] = oldpos. 


Returns: 


void 
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6.65.2.16 void gtk_list_store_set (GtkListStore + list_store, GtkTreelter + iter, ...) 


Sets the value of one or more cells in the row referenced by iter. 
The variable argument list should contain integer column numbers, each column number followed by the 
value to be set. The list is terminated by a -1. For example, to set column 0 with type G_TYPE_STRING 
to "Foo", you would write gtk_list_store_set (store, iter, O, "Foo", -1). 
Parameters: 

— list_store : A GtkListStore 

— iter : row iterator 


<—... : pairs of column number and value, terminated with -1 


Returns: 


void 


6.65.2.17 void gtk_list_store_set_column_types (GtkListStore x list_store, gint n_columns, GType 
* types) 


This function is meant primarily for GObjects that inherit from GtkListStore, and should only be used 
when constructing a new GtkListStore. 


It will not function after a row has been added, or a method on the GtkTreeModel interface is called. 


Parameters: 
< list_store : A GtkListStore 
< n_columns : Number of columns for the list store 


— types : An array length n of GTypes 


Returns: 


void 


6.65.2.18 void gtk_list_store_set_valist (GtkListStore x list_store, GtkTreelter x iter, va_list 
var_args) 


See gtk_list_store_set(); this version takes a va_list for use by language bindings. 


Parameters: 
— list_store : A GtkListStore 
—iter : A valid GtkTreelter for the row being modified 


— var_args : va_list of column/value pairs 


Returns: 


void 
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6.65.2.19 void gtk_list_store_set_value (GtkListStore + list_store, GtkTreelter x iter, gint column, 
GValue + value) 
Sets the data in the cell specified by iter and column. 


The type of value must be convertible to the type of the column. 


Parameters: 


< list_store : A GtkListStore 
< iter : A valid GtkTreelter for the row being modified 
— column : column number to modify 


< value : new value for the cell 


Returns: 


void 


6.65.2.20 void gtk_list_store_swap (GtkListStore « store, GtkTreelter « a, GtkTreelter + b) 


Swaps a and b in store. 


Note that this function only works with unsorted stores. 


Parameters: 


< list_store : A GtkListStore 
<a : A GtkTreelter. 
<b : Another GtkTreelter. 


Returns: 


void 
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6.66 GtkTreeStore 


6.66.1 Detailed Description 


The GtkTreeStore object is a list model for use with a GtkTree View widget. 


It implements the GtkTreeModel interface, and consequentialy, can use all of the methods available there. 
It also implements the GtkTreeSortable interface so it can be sorted by the view. Finally, 1t also implements 
the tree drag and drop interfaces. 


Data Structures 


struct _GtkTreeStore 


GtkTreeStore instance structure. 


struct _GtkTreeStoreClass 


GtkTreeStore instance class structure. 


Functions 


GtkTreeStore * gtk_tree_store_new (gint n_columns....) 


Creates a new tree store as with n_columns columns each of the types passed in. 


GtkTreeStore * gtk_tree_store_newv (gint n_columns, GType x*types) 


Non vararg creation function. 


void gtk_tree_store_set_column_types (GtkTreeStore *tree_store, gint n_columns, GType *types) 


This function is meant primarily for GObjects that inherit from GtkTreeStore, and should only be used when 
constructing a new GtkTreeStore. 


void gtk_tree_store_set_value (GtkTreeStore *tree_store, GtkTreelter xiter, gint column, GValue 
*value) 


Sets the data in the cell specified by iter and column. 


void gtk_tree_store_set (GtkTreeStore *tree_store, GtkTreelter xiter,...) 


Sets the value of one or more cells in the row referenced by iter. 


void gtk_tree_store_set_valist (GtkTreeStore xtree_store, GtkTreelter xiter, va_list var_args) 


See gtk_tree_store_set(); this version takes a va_list for use by language bindings. 


gboolean gtk_tree_store_remove (GtkTreeStore *tree_store, GtkTreelter xiter) 


Removes iter from tree_store. 


void gtk_tree_store_insert (GtkTreeStore *tree_store, GtkTreelter «iter, GtkTreelter «parent, gint 
position) 


Creates a new row at position. 


void gtk_tree_store_insert_before (GtkTreeStore *tree_store, GtkTreelter «iter, GtkTreelter «parent, 
GtkTreelter «sibling) 
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Inserts a new row before sibling. 


void gtk_tree_store_insert_after (GtkTreeStore *tree_store, GtkTreelter xiter, GtkTreelter «parent, 
GtkTreelter *sibling) 


Inserts a new row after sibling. 


void gtk_tree_store_insert_with_values (GtkTreeStore *tree_store, GtkTreelter xiter, GtkTreelter 
*parent, gint position,...) 


Creates a new row at position. 


void gtk_tree_store_insert_with_valuesv (GtkTreeStore *tree_store, GtkTreelter xiter, GtkTreelter 
*parent, gint position, gint «columns, GValue «values, gint n_values) 


A variant of gtk_tree_store_insert_with_values() which takes the columns and values as two arrays, instead 
of varargs. 


void gtk_tree_store_prepend (GtkTreeStore *tree_store, GtkTreelter «iter, GtkTreelter x*parent) 


Prepends a new row to tree_store. 


void gtk_tree_store_append (GtkTreeStore *tree_store, GtkTreelter «iter, GtkTreelter *parent) 


Appends a new row to tree_store. 


gboolean gtk_tree_store_is_ancestor (GtkTreeStore »tree_store, GtkTreelter xiter, GtkTreelter 
*descendant) 


Returns TRUE if iter is an ancestor of descendant. 


gint gtk_tree_store_iter_depth (GtkTreeStore *tree_store, GtkTreelter xiter) 


Returns the depth of iter. 


void gtk_tree_store_clear (GtkTreeStore «tree_store) 


Removes all rows from tree_store. 


gboolean gtk_tree_store_iter_is_valid (GtkTreeStore *tree_store, GtkTreelter xiter) 


Checks if the given iter is a valid iter for this GtkTreeStore. 


void gtk_tree_store_reorder (GtkTreeStore *tree_store, GtkTreelter «parent, gint *new_order) 


Reorders the children of parent in tree_store to follow the order indicated by new_order. 


void gtk_tree_store_swap (GtkTreeStore x*tree_store, GtkTreelter xa, GtkTreelter +b) 


Swaps a and b in the same level of tree_store. 


void gtk tree_store_move_before (GtkTreeStore xtree_store, GtkTreelter xiter, GtkTreelter 
*position) 


Moves iter in tree_store to the position before position. 


void gtk_tree_store_move_after (GtkTreeStore x*tree_store, GtkTreelter xiter, GtkTreelter 
*position) 


Moves iter in tree_store to the position after position. 
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6.66.2 Function Documentation 


6.66.2.1 void gtk_tree_store_append (GtkTreeStore x tree_store, GtkTreelter x iter, GtkTreelter x 
parent) 
Appends a new row to tree_store. 


If parent is non-NULL, then it will append the new row after the last child of parent, otherwise it will 
append a row to the top level. iter will be changed to point to this new row. The row will be empty after this 
function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). 


Parameters: 


tree_store [in] a GtkTreeStore 
iter [in] An unset GtkTreelter to set to the appended row 
parent [in] A valid GtkTreelter, or NULL 


Returns: 


void 


6.66.2.2 void gtk_tree_store_clear (GtkTreeStore x tree_store) 
Removes all rows from tree_store. 


Parameters: 


tree_store [in] a GtkTreeStore 


Returns: 


void 


6.66.2.3 void gtk_tree_store_insert (GtkTreeStore x tree_store, GtkTreelter x iter, GtkTreelter + 
parent, gint position) 
Creates a new row at position. 


If parent is non-NULL, then the row will be made a child of parent. Otherwise, the row will be created at 
the toplevel. If position is larger than the number of rows at that level, then the new row will be inserted to 
the end of the list. iter will be changed to point to this new row. The row will be empty after this function 
is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). 


Parameters: 


tree_store [in] a GtkTreeStore 
iter [in] An unset GtkTreelter to set to the new row 
parent [in] A valid GtkTreelter, or NULL 


position [in] position to insert the new row 


Returns: 


void 
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6.66.2.4 void gtk_tree_store_insert_after (GtkTreeStore x tree_store, GtkTreelter x iter, 
GtkTreelter « parent, GtkTreelter x sibling) 


Inserts a new row after sibling. 


If sibling is NULL, then the row will be prepended to parent ’s children. If parent and sibling are NULL, 
then the row will be prepended to the toplevel. If both sibling and parent are set, then parent must be the 
parent of sibling. When sibling is set, parent is optional. 


iter will be changed to point to this new row. The row will be empty after this function is called. To fill in 
values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). 
Parameters: 


tree_store [in] a GtkTreeStore 

iter [in] An unset GtkTreelter to set to the new row 
parent [in] A valid GtkTreelter, or NULL 

sibling [in] A valid GtkTreelter, or NULL 


Returns: 


void 


6.66.2.5 void gtk_tree_store_insert_before (GtkTreeStore « tree_store, GtkTreelter x iter, 
GtkTreelter « parent, GtkTreelter x sibling) 
Inserts a new row before sibling. 


If sibling is NULL, then the row will be appended to parent ’s children. If parent and sibling are NULL, 
then the row will be appended to the toplevel. If both sibling and parent are set, then parent must be the 
parent of sibling. When sibling is set, parent is optional. 


iter will be changed to point to this new row. The row will be empty after this function is called. To fill in 
values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). 
Parameters: 


tree_store [in] a GtkTreeStore 

iter [in] An unset GtkTreelter to set to the new row 
parent [in] A valid GtkTreelter, or NULL 

sibling [in] A valid GtkTreelter, or NULL 


Returns: 


void 


6.66.2.6 void gtk_tree_store_insert_with_values (GtkTreeStore « tree_store, GtkTreelter + iter, 
GtkTreelter x parent, gint position, ...) 


Creates a new row at position. 


iter will be changed to point to this new row. If position is larger than the number of rows on the list, then 
the new row will be appended to the list. The row will be filled with the values given to this function. 


Calling gtk_tree_store_insert_with_values (tree_store, iter, position, ...) has the same effect as calling 
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gtk_tree_store_insert (tree_store, iter, position); 
gtk_tree_store_set (tree_store, iter, ...); 


with the different that the former will only emit a row_inserted signal, while the latter will emit row_- 
inserted, row_changed and if the tree store is sorted, rows_reordered. Since emitting the rows_reordered 
signal repeatedly can affect the performance of the program, gtk_tree_store_insert_with_values() should 
generally be preferred when inserting rows in a sorted tree store. 


Parameters: 


tree_store [in] a GtkTreeStore 

iter [in] An unset GtkTreelter to set the new row, or NULL. 
parent [in] A valid GtkTreelter, or NULL 

position [in] position to insert the new row 


. [in] pairs of column number and value, terminated with -1 


Returns: 


void 


6.66.2.7 void gtk_tree_store_insert_with_valuesv (GtkTreeStore x tree_store, GtkTreelter + iter, 
GtkTreelter « parent, gint position, gint « columns, GValue = values, gint n_values) 


A variant of gtk_tree_store_insert_with_values() which takes the columns and values as two arrays, instead 
of varargs. 


This function is mainly intended for language bindings. 


Parameters: 


tree_store [in] a GtkTreeStore 

iter [in] An unset GtkTreelter to set the new row, or NULL. 
parent [in] A valid GtkTreelter, or NULL 

position [in] position to insert the new row 

columns [in] an array of column numbers 

values [in] an array of GValues 


n_values [in] the length of the columns and values arrays 


Returns: 


void 


6.66.2.8 gboolean gtk_tree_store_is_ancestor (GtkTreeStore « tree_store, GtkTreelter x iter, 
GtkTreelter « descendant) 


Returns TRUE if iter is an ancestor of descendant. 


That is, iter is the parent (or grandparent or great-grandparent) of descendant. 


Parameters: 


tree_store [in] a GtkTreeStore 
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iter [in] A valid GtkTreelter 
descendant [in] A valid GtkTreelter 


Returns: 


TRUE, if iter is an ancestor of descendant 


6.66.2.9 gint gtk_tree_store_iter_depth (GtkTreeStore x tree_store, GtkTreelter x iter) 


Returns the depth of iter. 


This will be O for anything on the root level, 1 for anything down a level, etc. 


Parameters: 


tree_store [in] a GtkTreeStore 
parent [in] A valid GtkTreelter 


Returns: 


The depth of iter 


6.66.2.10  gboolean gtk_tree_store_iter_is_valid (GtkTreeStore x tree_store, GtkTreelter x iter) 


Checks if the given iter is a valid iter for this GtkTreeStore. 


WARNING: This function is slow. Only use it for debugging and/or testing purposes. 


Parameters: 
tree_store [in] a GtkTreeStore 
iter [in] A GtkTreelter. 
Returns: 


TRUE if the iter is valid, FALSE if the iter is invalid. 


6.66.2.11 void gtk_tree_store_move_after (GtkTreeStore + tree_store, GtkTreelter x iter, 
GtkTreelter x position) 


Moves iter in tree_store to the position after position. 


iter and position should be in the same level. Note that this function only works with unsorted stores. If 
position is NULL, iter will be moved to the start of the level. 


Parameters: 


tree_store [in] A GtkTreeStore 
iter [in] A GtkTreelter. 
position [in] A GtkTreelter. 


Returns: 


void 
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6.66.2.12 void gtk_tree_store_move_before (GtkTreeStore « tree_store, GtkTreelter « iter, 
GtkTreelter x position) 


Moves iter in tree_store to the position before position. 
iter and position should be in the same level. Note that this function only works with unsorted stores. If 
position is NULL, iter will be moved to the end of the level. 
Parameters: 
tree_store [in] a GtkTreeStore 
iter [in] A GtkTreelter. 
position [in] A GtkTreelter or NULL. 


Returns: 


void 


6.66.2.13 GtkTreeStorex gtk_tree_store_new (gint n_columuns, ...) 


Creates a new tree store as with n_columns columns each of the types passed in. 
Note that only types derived from standard GObject fundamental types are supported. 


As an example, gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_PIXBUF); will 
create a new GtkTreeStore with three columns, of type int, string and GdkPixbuf respectively. 


Parameters: 
n_columns [in] number of columns in the tree store 


. [in] all GType types for the columns, from first to last 


Returns: 


a new GtkTreeStore 


6.66.2.14 GtkTreeStore* gtk_tree_store_newv (gint n_columns, GType = types) 


Non vararg creation function. 


Used primarily by language bindings. 


Parameters: 
n_columns [in] number of columns in the tree store 


types [in] an array of GType types for the columns, from first to last 


Returns: 


a new GtkTreeStore 
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6.66.2.15 void gtk_tree_store_prepend (GtkTreeStore x tree_store, GtkTreelter « iter, GtkTreelter 
* parent) 

Prepends a new row to tree_store. 
If parent is non-NULL, then it will prepend the new row before the first child of parent, otherwise it will 
prepend a row to the top level. iter will be changed to point to this new row. The row will be empty after this 
function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). 
Parameters: 

tree_store [in] a GtkTreeStore 

iter [in] An unset GtkTreelter to set to the prepended row 


parent [in] A valid GtkTreelter, or NULL 


Returns: 


void 


6.66.2.16 gboolean gtk_tree_store_remove (GtkTreeStore « tree_store, GtkTreelter x iter) 


Removes iter from tree_store. 


After being removed, iter is set to the next valid row at that level, or invalidated if it previously pointed to 
the last one. 


Parameters: 


tree_store [in] a GtkTreeStore 
iter [in] A valid GtkTreelter 


Returns: 


TRUE if iter is still valid, FALSE if not. 


6.66.2.17 void gtk_tree_store_reorder (GtkTreeStore x tree_store, GtkTreelter x parent, gint « 
new_order) 
Reorders the children of parent in tree_store to follow the order indicated by new_order. 


Note that this function only works with unsorted stores. 


Parameters: 


tree_store [in] a GtkTreeStore 
parent [in] A GtkTreelter. 


new_order [in] an array of integers mapping the new position of each child to its old position before 
the re-ordering, i.e. new_order[newpos] = oldpos. 


Returns: 


void 
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6.66.2.18 void gtk_tree_store_set (GtkTreeStore + tree_store, GtkTreelter x iter, ...) 


Sets the value of one or more cells in the row referenced by iter. 
The variable argument list should contain integer column numbers, each column number followed by the 
value to be set. The list is terminated by a -1. For example, to set column 0 with type G_TYPE_STRING 
to "Foo", you would write gtk_tree_store_set (store, iter, 0, "Foo", -1). 
Parameters: 

tree_store [in] a GtkTreeStore 

iter [in] A valid GtkTreelter for the row being modified 


. [in] pairs of column number and value, terminated with -1 


Returns: 


void 


6.66.2.19 void gtk_tree_store_set_column_types (GtkTreeStore + tree_store, gint n_columns, 
GType +* types) 


This function is meant primarily for GObjects that inherit from GtkTreeStore, and should only be used 
when constructing a new GtkTreeStore. 


It will not function after a row has been added, or a method on the GtkTreeModel interface is called. 


Parameters: 
tree_store [in] a GtkTreeStore 
n_columns [in] Number of columns for the tree store 


types [in] An array of GType types, one for each column 


Returns: 


void 


6.66.2.20 void gtk_tree_store_set_valist (GtkTreeStore > tree_store, GtkTreelter x iter, va_list 
var_args) 


See gtk_tree_store_set(); this version takes a va_list for use by language bindings. 


Parameters: 
tree_store [in] a GtkTreeStore 
iter [in] A valid GtkTreelter for the row being modified 


var_args [in] va_list of column/value pairs 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


632 Module Documentation 


6.66.2.21 void gtk_tree_store_set_value (GtkTreeStore x tree_store, GtkTreelter x iter, gint 
column, GValue x value) 
Sets the data in the cell specified by iter and column. 


The type of value must be convertible to the type of the column. 


Parameters: 


tree_store [in] a GtkTreeStore 
iter [in] A valid GtkTreelter for the row being modified 
column [in] column number to modify 


value [in] new value for the cell 


Returns: 


void 


6.66.2.22 void gtk_tree_store_swap (GtkTreeStore x tree_store, GtkTreelter « a, GtkTreelter x b) 


Swaps a and b in the same level of tree_store. 


Note that this function only works with unsorted stores. 


Parameters: 


tree_store [in] a GtkTreeStore 
a [in] A GtkTreelter. 
b [in] Another GtkTreelter. 


Returns: 


void 
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6.67 Menus, Combo Box, Toolbar 


Modules 


+ GtkMenu 


A GtkMenu is a GtkMenuShell that implements a drop down menu consisting of a list of GtkMenultem 
objects which can be navigated and activated by the user to perform application functions. 


e GtkMenultem 
The GtkMenultem widget and the derived widgets are the only valid childs for menus. 


GtkMenuShell 


A GtkMenuShell is the abstract base class used to derive the GtkMenu and GtkMenuBar subclasses. 


GtkCheckMenultem 


A GtkCheckMenultem is a menu item that maintains the state of a boolean value in addition to a GtkMenu- 
Item’s usual role in activating application code. 


+ GtkRadioMenultem 


A radio menu item is a check menu item that belongs to a group. 


GtkComboBox 


A GtkComboBox is a widget that allows the user to choose from a list of valid choices. 
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6.68 GtkMenu 


6.68.1 Detailed Description 


A GtkMenu is a GtkMenuShell that implements a drop down menu consisting of a list of GtkMenultem 
objects which can be navigated and activated by the user to perform application functions. 


A GtkMenu is most commonly dropped down by activating a GtkMenultem in a GtkMenuBar or popped 
up by activating a GtkMenultem in another GtkMenu. 


Applications can display a GtkMenu as a popup menu by calling the gtk_menu_popup() function. GtkMenu 
is enhanced for Mobile environment by providing support to associate with Softkey bar. 
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Figure 6.14: GtkMenu 


Code Example: 


GtkWidget *menu; 
GtkWidget *menuitem; 
GtkWidget *form; 


menu = gtk_menu_new(); 

form = gtk_form_new (TRUE); 
gtk_form_add_softkey (GTK_FORM (form) , SOFTKEY_LEFT, "popup", 

NULL, (SoftkeyActionType) SOFTKEY_MENU, GTK_MENU (menu) , NULL) ; 


menuitem = gtk_menu_item_new_with_label ("iteml"); 
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menuitem); 


gtk_widget_show (menu) ; 
gtk_widget_show (menuitem) ; 
gtk_widget_show (form); 
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Modified for 
LIMO RI 


Data Structures 


e struct _GtkMenu 


GtkMenu instance structure. 


e struct _GtkMenuClass 


GTK Native GtkMenu instance class structure. 


Functions 


e GtkWidget * gtk_menu_new (void) 


Create A new menu. 


e void gtk_menu_popup (GtkMenu *menu, GtkWidget *parent_menu_shell, GtkWidget *parent_- 
menu_item, GtkMenuPositionFunc func, gpointer data, guint button, guint32 activate_time) 


Displays a menu and makes it available for selection. 


e void gtk_menu_reposition (GtkMenu *menu) 


Position the menu according to its position function. 


e void gtk_menu_popdown (GtkMenu *menu) 


Removes the menu from the screen. 


e GtkWidget * gtk_menu_get_active (GtkMenu *menu) 


Return the selected menu item from the menu. 


e void gtk_menu_set_active (GtkMenu *menu, guint index_) 


Selects the specified menu item within the menu. 


e void gtk_menu_attach_to_widget (GtkMenu *menu, GtkWidget xattach_widget, GtkMenuDetach- 
Func detacher) 


Attaches the menu to the widget and provides a callback function that will be invoked when the menu calls 
gtk_menu_detach() during its destruction. 


e void gtk_menu_detach (GtkMenu *menu) 


Detaches the menu from the widget to which it had been attached. 


e GtkWidget * gtk_menu_get_attach_widget (GtkMenu *menu) 


Returns the GtkWidget that the menu is attached to. 


e guint gtk_menu_get_attach_softkey_position (GtkMenu *menu) 


Get the softkey position if the menu is attached to a softkeybar. 


e void gtk_menu_set_attach_softkey_position (GtkMenu *menu, guint position) 


Set the softkey position if the menu is attached to a softkeybar. 
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e void gtk_menu_set_accel_group (GtkMenu *menu, GtkAccelGroup x*accel_group) 


FORO cor: all the functions below are deprecated in LIMO 
SOR CK aR a kk a 2k A 


e GtkAccelGroup * gtk_menu_get_accel_group (GtkMenu *menu) 


Gets the GtkAccelGroup which holds global accelerators for the menu. 


e void gtk_menu_set_accel_path (GtkMenu *menu, const gchar *accel_path) 


Sets an accelerator path for this menu from which accelerator paths for its immediate children, its menu 
items, can be constructed. 


6.68.2 Function Documentation 


6.68.2.1 void gtk_menu_attach_to_widget (GtkMenu x menu, GtkWidget x attach_widget, 
GtkMenuDetachFunc detacher) 


Attaches the menu to the widget and provides a callback function that will be invoked when the menu calls 
gtk_menu_detach() during its destruction. 


a particular widget. This is typically a menu item; it may also be a widget with a popup menu - for instance, 
the Notebook widget. 


Parameters: 


menu [in] A GtkMenu. 
attach_widget [in] The GtkWidget that the menu will be attached to. 


detacher [in] The user supplied callback function that will be called when the menu calls gtk_menu_- 
detach(). 


6.68.2.2 void gtk_menu_detach (GtkMenu x menu) 


Detaches the menu from the widget to which it had been attached. 


This function will call the callback function, detacher, provided when the gtk_menu_attach_to_widget() 
function was called. 


Parameters: 


menu [in] A GtkMenu, the menu to detach. 


6.68.2.3 GtkAccelGroup* gtk_menu_get_accel_group (GtkMenu * menu) 


Gets the GtkAccelGroup which holds global accelerators for the menu. 


See gtk_menu_set_accel_group(). 


Parameters: 
menu [in] a GtkMenu. 
Returns: 


the GtkAccelGroup associated with the menu. 
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6.68.2.4 GtkWidget gtk_menu_get_active (GtkMenu x menu) 

Return the selected menu item from the menu. 

Returns the selected menu item from the menu. This is used by the GtkOptionMenu. 
Parameters: 


menu [in] A GtkMenu. 


Returns: 


The GtkMenultem that was last selected in the menu. If a selection has not yet been made, the first 
menu item is selected. 


Remarks: 


This is used by the GtkOptionMenu and should not be used by anyone else. 


6.68.2.5 guint gtk_menu_get_attach_softkey_position (GtkMenu * menu) 


Get the softkey position if the menu is attached to a softkeybar. 


Parameters: 


<— menu the menu to get. 


Returns: 


void. 


Since 


LIMO R1 


6.68.2.6 GtkWidget» gtk_menu_get_attach_widget (GtkMenu x menu) 


Returns the GtkWidget that the menu is attached to. 


This should be dumped in favor of data set when the menu is popped up - that is currently in the ItemFactory 
code, but should be in the Menu code. 


Parameters: 


menu [in] A GtkMenu. 


Returns: 


The GtkWidget that the menu is attached to. 


6.68.2.7 GtkWidget» gtk_menu_new (void) 


Create A new menu. 


Returns: 


A new widget. 
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6.68.2.8 void gtk_menu_popdown (GtkMenu * menu) 


Removes the menu from the screen. 


Modification: This method is modified for Mobile environment. If the Menu is attached with Softkey Bar, 
then during menu popupafter popup, Softkey names are renamed specific to Menu operation ( More or 
Select and Cancel ). On Popdown, the softkey names are replaced with original name. 


Parameters: 


menu [in] the menu to pop down. 


Returns: 


void. 


Modified for 
LIMO RI 


6.68.2.9 void gtk_menu_popup (GtkMenu x menu, GtkWidget x parent_menu_shell, GtkWidget x 
parent_menu_item, GtkMenuPositionFunc func, gpointer data, guint button, guint32 
activate_time) 


Displays a menu and makes it available for selection. 


Applications can use this function to display context-sensitive menus, and will typically supply NULL 
for the parent_menu_shell, parent_menu_item, func and data parameters. The default menu positioning 
function will position the menu at the current mouse cursor position. 


The button parameter should be the mouse button pressed to initiate the menu popup. If the menu popup 
was initiated by something other than a mouse button press, such as a mouse button release or a keypress, 
button should be 0. 


The activate_time parameter should be the time stamp of the event that initiated the popup. If such an event 
is not available, use gtk_get_current_event_time() instead. 


Modification: This method is modified for Mobile environment. If the Menu is attached with Softkey Bar, 
then after menu popup, Softkey names are renamed specific to Menu operation( More or Select and Cancel 


). 
Parameters: 


menu [in] the menu to pop up. 

parent_menu_shell [in] menu’s parent menu shell. 
parent_menu_item [in] menu’s parent menu item. 

func [in] position function of popup. 

data [in] user supplied data to be passed to func. 

button [in] the mouse button which was pressed to initiate the event. 


activate_time [in] the time at which the activation event occurred. 
Returns: 

void 
Modified for 

LIMO RI 
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6.68.2.10 void gtk_menu_reposition (GtkMenu * menu) 
Position the menu according to its position function. 
Called from gtkmenuitem.c when a menu-item changes its allocation. 
Parameters: 

menu [in] the menu to reposition. 


Modification: This function is modified to place the menu popup according to its associated Softkey. 


Returns: 


void. 


Modified for 
LIMO RI 


6.68.2.11 void gtk_menu_set_accel_group (GtkMenu * menu, GtkAccelGroup x accel_group) 


ORO Oncor: all the functions below are deprecated in LIMO 
Fo Kee k k k/// 


Set the GtkAccelGroup which holds global accelerators for the menu. This accelerator group needs to also 
be added to all windows that this menu is being used in with gtk_window_add_accel_group(), in order for 
those windows to support all the accelerators contained in this group. 


Parameters: 


menu [in] a GtkMenu. 


accel_group [in] the GtkAccelGroup to be associated with the menu.. 


Returns: 


void. 


6.68.2.12 void gtk_menu_set_accel_path (GtkMenu * menu, const gchar + accel_path) 


Sets an accelerator path for this menu from which accelerator paths for its immediate children, its menu 
items, can be constructed. 


The main purpose of this function is to spare the programmer the inconvenience of having to call gtk_- 
menu_item_set_accel_path() on each menu item that should support runtime user changable accelerators. 
Instead, by just calling gtk_menu_set_accel_path() on their parent, each menu item of this menu, that 
contains a label describing its purpose, automatically gets an accel path assigned. 


For example, a menu containing menu items "New" and "Exit", will, after gtk_menu_set_accel_path 
(menu, "<Gnumeric-Sheet>/File"); has been called, assign its items the accel paths: "<Gnumeric- 
Sheet>/File/New" and "<Gnumeric-Sheet>/File/Exit". Assigning accel paths to menu items then enables 
the user to change their accelerators at runtime. More details about accelerator paths and their default 
setups can be found at gtk_accel_map_add_entry(). 


Parameters: 


menu [in] a GtkMenu. 
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accel_path [in] a valid accelerator path 


Returns: 


void 


6.68.2.13 void gtk_menu_set_active (GtkMenu * menu, guint index_) 


Selects the specified menu item within the menu. 


This is used by the GtkOptionMenu and should not be used by anyone else 


Parameters: 


menu [in] A GtkMenu. 


index_ [in] The index of the menu item to select. Index values are from 0 to n-1. 


Remarks: 


This is used by the GtkOptionMenu and should not be used by anyone else. 


6.68.2.14 void gtk_menu_set_attach_softkey_position (GtkMenu x menu, guint position) 


Set the softkey position if the menu is attached to a softkeybar. 


Parameters: 


< menu the menu to set. 


— position softkey’s position the menu is set. 


Returns: 


void. 


Since 


LIMO RI 
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6.69 GtkMenultem 


6.69.1 Detailed Description 


The GtkMenultem widget and the derived widgets are the only valid childs for menus. 

Their function is to correctly handle highlighting, alignment, events and submenus. 

As it derives from GtkBin it can hold any valid child widget, altough only a few are really useful. 
Code Example: 


GtkWidget *menu; 
GtkWidget *menuitem; 


menu = gtk_menu_new(); 
menuitem = gtk_menu_item_new_with_label ("iteml"); 
g_signal_connect (G_OBJECT (menuitem), "activate", 


G_CALLBACK (menuitem_activate), NULL); 
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menuitem); 
gtk_widget_show (menu) ; 
gtk_widget_show (menuitem) ; 

//possible 

GtkWidget «submenu; 

submenu = gtk_menu_new(); 

gtk_menu_item_set_submenu (GTK_MENU_ITEM (menuitem), submenu) ; 
gtk_widget_show (submenu) ; 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkMenultem 


GtkMenultem instance structure. 


e struct _GtkMenultemClass 


GTK Native GtkMenultem instance class structure. 


Functions 


e GtkWidget x* gtk_menu_item_new (void) 


Creates a new GtkMenultem. 


e GtkWidget * gtk_menu_item_new_with_label (const gchar label) 
Creates a new GtkMenultem whose child is a GtkLabel. 


e void gtk_menu_item_set_submenu (GtkMenultem *menu_item, GtkWidget «submenu) 


Sets the widget submenu, or changes it. 


e GtkWidget * gtk_menu_item_get_submenu (GtkMenultem *menu_item) 


Gets the submenu underneath this menu item, if any. 


e void gtk_menu_item_remove_submenu (GtkMenultem *menu_item) 
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Removes the widget's submenu. 


e void gtk_menu_item_select (GtkMenultem *menu_item) 


Emits the "select" signal on the given item. 


e void gtk_menu_item_deselect (GtkMenultem *menu_item) 


Emits the "deselect" signal on the given item. 


e void gtk_menu_item_activate (GtkMenultem *menu_item) 


Emits the "activate" signal on the given item. 


e void gtk_menu_item_toggle_size_request (GtkMenultem *menu_item, gint *requisition) 


Emits the "toggle_size_request" signal on the given item. 


e void gtk_menu_item_toggle_size_allocate (GtkMenultem *menu_item, gint allocation) 


Emits the "toggle_size_allocate" signal on the given item. 


e gint gtk_menu_item_get_index (GtkWidget *menu_item) 


Get the index of the specified menu item in the menu it resides in. 


e void gtk_menu_item_set_right_justified (GtkMenultem *menu_item, gboolean right_justified) 


brief [deprecated] Sets whether the menu item appears justified at the right side of a menu bar. 


e gboolean gtk_menu_item_get_right_justified (GtkMenultem *menu_item) 


Get whether the menu item appears justified at the right side of the menu bar. 


e void gtk_menu_item_set_accel_path (GtkMenultem *menu_item, const gchar *accel_path) 


[deprecated] Set the accelerator path on menu_item, through which runtime changes of the menu item’s 
accelerator caused by the user can be identified and saved to persistant storage (see gtk_accel_map_save() 
on this). 


e GtkWidget * gtk_menu_item_new_with_mnemonic (const gchar xlabel) 


[deprecated] Creates a new GtkMenultem containing a label. 


6.69.2 Function Documentation 
6.69.2.1 void gtk_menu_item_activate (GtkMenultem * menu_item) 


Emits the "activate" signal on the given item. 


Parameters: 


<— menu_item the menu item 


Returns: 


void 
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6.69.2.2 void gtk_menu_item_deselect (GtkMenultem x* menu_item) 


Emits the "deselect" signal on the given item. 


Behaves exactly like gtk_item_deselect. 


Parameters: 


< menu_item the menu item 


Returns: 


void 


6.69.2.3 gint gtk_menu_item_get_index (GtkWidget x menu_item) 


Get the index of the specified menu item in the menu it resides in. 


Parameters: 


— menu_item the specified menu item. 


Returns: 


The index,-1 if fail. 


Since 


LIMO R1 


6.69.2.4 gboolean gtk_menu_item_get_right_justified (GtkMenultem x* menu_item) 


Get whether the menu item appears justified at the right side of the menu bar. 


Parameters: 


<— menu_item a GtkMenultem 


Returns: 


TRUE if the menu item will appear at the far right if added to a menu bar. 


6.69.2.5 GtkWidget» gtk_menu_item_get_submenu (GtkMenultem * menu_item) 


Gets the submenu underneath this menu item, if any. 
See gtk_menu_item_set_submenu(). 
Parameters: 

< menu_item A GtkMenultem. 
Returns: 

submenu for this menu item, or NULL if none. 
See also: 


gtk_menu_item_set_submenu() 
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6.69.2.6 GtkWidget gtk_menu_item_new (void) 
Creates a new GtkMenultem. 


Returns: 


the newly created GtkMenultem 


6.69.2.7 GtkWidget gtk_menu_item_new_with_label (const gchar + label) 


Creates a new GtkMenultem whose child is a GtkLabel. 


Parameters: 


— label the text for the label 


Returns: 


the newly created GtkMenultem 


6.69.2.8 GtkWidget« gtk_menu_item_new_with_mnemonic (const gchar + label) 


[deprecated] Creates a new GtkMenultem containing a label. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the menu item. 


Parameters: 


< label The text of the button, with an underscore in front of the mnemonic character 


Returns: 


ta new GtkMenultem 


Deprecated 
LIMO R1 


6.69.2.9 void gtk_menu_item_remove_submenu (GtkMenultem x menu_item) 


Removes the widget's submenu. 


Parameters: 


— menu_item the menu item widget 


Returns: 


void 
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6.69.2.10 void gtk_menu_item_select (GtkMenultem * menu_item) 


Emits the "select" signal on the given item. 


Behaves exactly like gtk_item_select. 


Parameters: 


< menu_item the menu item 


Returns: 


void 


6.69.2.11 void gtk_menu_item_set_accel_path (GtkMenultem x menu_item, const gchar x 
accel_path) 


[deprecated] Set the accelerator path on menu_item, through which runtime changes of the menu item’s 
accelerator caused by the user can be identified and saved to persistant storage (see gtk_accel_map_save() 
on this). 


To setup a default accelerator for this menu item, call gtk_accel_map_add_entry() with the same accel_- 
path. See also gtk_accel_map_add_entry() on the specifics of accelerator paths, and gtk_menu_set_accel_- 
pathQ for a more convenient variant of this function. 


This function is basically a convenience wrapper that handles calling gtk_widget_set_accel_path() with the 
appropriate accelerator group for the menu item. 


Note that you do need to set an accelerator on the parent menu with gtk_menu_set_accel_group() for this 
to work. 


Parameters: 


<— menu_item a valid GtkMenultem 


— accel_path accelerator path, corresponding to this menu item’s functionality, or NULL to unset the 
current path. 


Returns: 
void 
Deprecated 
LIMO R1 


6.69.2.12 void gtk_menu_item_set_right_justified (GtkMenultem x menu_item, gboolean 
right_justified) 


brief [deprecated] Sets whether the menu item appears justified at the right side of a menu bar. 


This was traditionally done for "Help" menu items, but is now considered a bad idea. (If the widget layout 
is reversed for a right-to-left language like Hebrew or Arabic, right-justified-menu-items appear at the 
left.) 


Parameters: 


< menu_item a GtkMenultem. 
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— right_justified if TRUE the menu item will appear at the far right if added to a menu bar 
Returns: 

void 
Remarks: 


Only useful for menu bars. 


Deprecated 
LIMO R1 


6.69.2.13 void gtk_menu_item_set_submenu (GtkMenultem x menu_item, GtkWidget x submenu) 


Sets the widget submenu, or changes it. 


Parameters: 


<— menu_item the menu item widget 


< submenu the submenu 
See also: 


gtk_menu_item_get_submenu() 


Returns: 


void 


6.69.2.14 void gtk_menu_item_toggle_size_allocate (GtkMenultem x menu_item, gint allocation) 


Emits the "toggle_size_allocate" signal on the given item. 


Parameters: 


<— menu_item the menu item. 


< allocation the allocation to use as signal data. 


Returns: 


void 


6.69.2.15 void gtk_menu_item_toggle_size_request (GtkMenultem + menu_item, gint x requisition) 


Emits the "toggle_size_request" signal on the given item. 


Parameters: 

<— menu_item the menu item 

— requisition The requisition to use as signal data. 
Returns: 


void 
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6.70 GtkMenuShell 


6.70.1 Detailed Description 


A GtkMenuShell is the abstract base class used to derive the GtkMenu and GtkMenuBar subclasses. 


A GtkMenuShell is a container of GtkMenultem objects arranged in a list which can be navigated, selected, 
and activated by the user to perform application functions. A GtkMenultem can have a submenu associated 
with it, allowing for nested hierarchical menus. 


Code Example: 


GtkWidget *menu; 

GtkWidget «menuitem; 

menu = gtk_menu_new(); 
gtk_form_add_softkey (GTK_FORM (form) , SOFTKEY_LEFT, "popup", 

NULL, (SoftkeyActionType) SOFTKEY_MENU, GTK_MENU (menu) , NULL) ; 
menuitem = gtk_menu_item_new_with_label ("iteml"); 

gtk_menu_shell_append (GTK_MENU_SHELL (menu), menuitem); 
gtk_widget_show (menu) ; 

gtk_widget_show (menuitem) ; 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkMenuShell 


GtkMenuShell instance structure. 


e struct _GtkMenuShellClass 


GTK Native GtkMenuShell instance class structure. 


Functions 


e void gtk_menu_shell_append (GtkMenuShell *menu_shell, Gtk Widget *child) 


Adds a new GtkMenultem to the end of the menu shell’s item list. 


e void gtk_menu_shell_prepend (GtkMenuShell *menu_shell, Gtk Widget *child) 


Adds a new GtkMenultem to the beginning of the menu shell’s item list. 


e void gtk_menu_shell_insert (GtkMenuShell «*menu_shell, GtkWidget child, gint position) 


Adds a new GtkMenultem to the menu shell’s item list at the position indicated by position. 


e void gtk_menu_shell_deactivate (GtkMenuShell *menu_shell) 


Deactivates the menu shell. 


e void gtk_menu_shell_select_item (GtkMenuShell *menu_shell, Gtk Widget *menu_item) 


Selects the menu item from the menu shell. 


e void gtk_menu_shell_deselect (GtkMenuShell *menu_shell) 
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Deselects the currently selected item from the menu shell, if any. 


e void gtk_menu_shell_activate_item (GtkMenuShell x*menu_shell, GtkWidget *menu_item, 
gboolean force_deactivate) 


Activates the menu item within the menu shell. 


e void gtk_menu_shell_select_first (GtkMenuShell *menu_shell, gboolean search_sensitive) 


Select the first visible or selectable child of the menu shell; don’t select tearoff items unless the only item is 
a tearoff item. 


e void gtk_menu_shell_cancel (GtkMenuShell *menu_shell) 


Cancel the selection within the menu shell. 


e gboolean gtk_menu_shell_get_take_focus (GtkMenuShell *«menu_shell) 


Returns TRUE if the menu shell will take the keyboard focus on popup. 


e void gtk_menu_shell_set_take_focus (GtkMenuShell *«menu_shell, gboolean take_focus) 


If take_focus is TRUE (the default) the menu shell will take the keyboard focus so that it will receive all 
keyboard events which is needed to enable keyboard navigation in menus. 


6.70.2 Function Documentation 


6.70.2.1 void gtk_menu_shell_activate_item (GtkMenuShell x menu_shell, GtkWidget x 
menu_item, gboolean force_deactivate) 


Activates the menu item within the menu shell. 


Parameters: 


< menu_shell a GtkMenuShell. 
< menu_item The GtkMenultem to activate. 


— force_deactivate If TRUE, force the deactivation of the menu shell after the menu item is activated. 


Returns: 


void 


6.70.2.2 void gtk_menu_shell_append (GtkMenuShell x menu_shell, GtkWidget « child) 
Adds a new GtkMenultem to the end of the menu shell’s item list. 


Parameters: 


< menu_shell a GtkMenuShell. 
— child The GtkMenultem to add. 


Returns: 


void 
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6.70.2.3 void gtk_menu_shell_cancel (GtkMenuShell * menu_shell) 
Cancel the selection within the menu shell. 


Parameters: 


< menu_shell A GtkMenuShell. 


Returns: 


void 


6.70.2.4 void gtk_menu_shell_deactivate (GtkMenuShell « menu_shell) 


Deactivates the menu shell. 


Typically this results in the menu shell being erased from the screen. 


Parameters: 


< menu_shell a GtkMenuShell. 


Returns: 


void 


6.70.2.5 void gtk_menu_shell_deselect (GtkMenuShell x menu_shell) 


Deselects the currently selected item from the menu shell, if any. 


Parameters: 


< menu_shell a GtkMenuShell. 


Returns: 


void 


6.70.2.6 gboolean gtk_menu_shell_get_take_focus (GtkMenuShell x menu_shell) 


Returns TRUE if the menu shell will take the keyboard focus on popup. 


Parameters: 


< menu_shell A GtkMenuShell. 


Returns: 


TRUE if the menu shell will take the keyboard focus on popup, FALSE if not. 
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6.70.2.7 void gtk_menu_shell_insert (GtkMenuShell x menu_shell, GtkWidget « child, gint 
position) 


Adds a new GtkMenultem to the menu shell’s item list at the position indicated by position. 


Parameters: 


< menu_shell a GtkMenuShell. 
— child The GtkMenultem to add. 


— position The position in the item list where child is added. Positions are numbered from 0 to n-1. 


Returns: 


void 


6.70.2.8 void gtk_menu_shell_prepend (GtkMenuShell x menu_shell, GtkWidget « child) 


Adds a new GtkMenultem to the beginning of the menu shell’s item list. 


Parameters: 


< menu_shell a GtkMenuShell. 
— child The GtkMenultem to add. 


Returns: 


void 


6.70.2.9 void gtk_menu_shell_select_first (GtkMenuShell x menu_shell, gboolean search_sensitive) 


Select the first visible or selectable child of the menu shell; don’t select tearoff items unless the only item 
is a tearoff item. 


Parameters: 


< menu_shell a GtkMenuShell. 


— search_sensitive if TRUE, search for the first selectable menu item, otherwise select nothing if the 
first item isn’t sensitive. This should be FALSE if the menu is being popped up initially. 


Returns: 


void 


6.70.2.10 void gtk_menu_shell_select_item (GtkMenuShell x menu_shell, GtkWidget x menu_item) 


Selects the menu item from the menu shell. 
Parameters: 


< menu_shell a GtkMenuShell. 
< menu_item The GtkMenultem to select. 


Returns: 


void 
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6.70.2.11 void gtk_menu_shell_set_take_focus (GtkMenuShell x menu_shell, gboolean take_focus) 


If take_focus is TRUE (the default) the menu shell will take the keyboard focus so that it will receive all 
keyboard events which is needed to enable keyboard navigation in menus. 


Setting take_focus to FALSE is useful only for special applications like virtual keyboard implementations 
which should not take keyboard focus. 


The take_focus state of a menu or menu bar is automatically propagated to submenus whenever a submenu 
is popped up, so you don’t have to worry about recursively setting it for your entire menu hierarchy. Only 
when programmatically picking a submenu and popping it up manually, the take_focus property of the 
submenu needs to be set explicitely. 


Note that setting it to FALSE has side-effects: 


If the focus is in some other app, it keeps the focus and keynav in the menu doesn’t work. Consequently, 
keynav on the menu will only work if the focus is on some toplevel owned by the onscreen keyboard. 


To avoid confusing the user, menus with take_focus set to FALSE should not display mnemonics or accel- 
erators, since it cannot be guaranteed that they will work. 


See also gdk_keyboard_grab() 


Parameters: 


— menu_shell A GtkMenuShell. 
— take_focus TRUE if the menu shell should take the keyboard focus on popup. 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


652 Module Documentation 


6.71 GtkCheckMenultem 


6.71.1 Detailed Description 


A GtkCheckMenultem is a menu item that maintains the state of a boolean value in addition to a GtkMe- 
nultem’s usual role in activating application code. 


A check box indicating the state of the boolean value is displayed at the left side of the GtkMenultem. 
Activating the GtkMenultem toggles the value. 


Code Example: 
GtkWidget *menu; 


GtkWidget *checkmenuiteml; 
GtkWidget *checkmenuitem2; 


menu = gtk_menu_new(); 
checkmenuiteml = gtk_check_menu_item_new_with_label ("iteml"); 
checkmenuitem2 = gtk_check_menu_item_new_with_label ("item2"); 


// these two signals are both emited when the check menu item is activated, 

// so you can use only one of them. 

g_signal_connect (G_OBJECT (checkmenuiteml), "activate", 
G_CALLBACK (menuiteml_activate), NULL); 

g_signal_connect (G_OBJECT (checkmenuiteml), "toggled", 
G_CALLBACK (menuiteml_toggled), NULL); 

gtk_menu_shell_append (GTK_MENU_SHELL (menu), checkmenuiteml); 

gtk_menu_shell_append (GTK_MENU_SHELL (menu), checkmenuitem2) ; 

gtk_widget_show (menu) ; 

gtk_widget_show(checkmenuiteml); 

gtk_widget_show(checkmenuitem2); 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkCheckMenultem 


GtkCheckMenultem instance structure. 


¢ struct _GtkCheckMenultemClass 


GTK Native GtkCheckMenultem instance class structure. 


Functions 


e GtkWidget * gtk_check_menu_item_new (void) 


Creates a new GtkCheckMenultem. 


e GtkWidget * gtk_check_menu_item_new_with_label (const gchar xlabel) 


Creates a new GtkCheckMenultem with a label. 


e void gtk_check_menu_item_set_active (GtkCheckMenultem *check_menu_item, gboolean is_- 
active) 


Set the active state of the menu item’s check box. 
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e gboolean gtk_check_menu_item_get_active (GtkCheckMenultem *check_menu_item) 


Returns whether the check menu item is active. 


e void gtk_check_menu_item_toggled (GtkCheckMenultem *check_menu_item) 


Emits the GtkCheckMenultem: :toggled signal. 


e GtkWidget * gtk_check_menu_item_new_with_mnemonic (const gchar «label) 


[deprecated] Creates a new GtkCheckMenultem containing a label. 


e void gtk_check_menu_item_set_inconsistent (GtkCheckMenultem *check_menu_item, gboolean 
setting) 


[deprecated] If the user has selected a range of elements (such as some text or spreadsheet cells) that are 
affected by a boolean setting, and the current values in that range are inconsistent, you may want to display 
the check in an "in between" state. 


e gboolean gtk_check_menu_item_get_inconsistent (GtkCheckMenultem *check_menu_item) 


[deprecated] Returns the inconsistent value, That is value set by gtk_check_menu_item_set_inconsistent(). 


e void gtk_check_menu_item_set_draw_as_radio (GtkCheckMenultem *check_menu_item, gboolean 
draw_as_radio) 


[deprecated] Sets whether check_menu_item is drawn like a GtkRadioMenultem 


e gboolean gtk_check_menu_item_get_draw_as_radio (GtkCheckMenultem *check_menu_item) 


[deprecated] Returns whether check_menu_item looks like a GtkRadioMenultem 


6.71.2 Function Documentation 


6.71.2.1 gboolean gtk_check_menu_item_get_active (GtkCheckMenultem x check_menu_item) 


Returns whether the check menu item is active. 


See gtk_check_menu_item_set_active(). 


Parameters: 


— check_menu_item : A GtkCheckMenultem. 


Returns: 


TRUE if the menu item’s check box is active, FALSE if not. 


6.71.2.2 gboolean gtk_check_menu_item_get_draw_as_radio (GtkCheckMenultem + 
check_menu_item) 


[deprecated] Returns whether check_menu_item looks like a GtkRadioMenultem 


Parameters: 


— check_menu_item : GtkCheckMenultem 
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Returns: 


Whether check_menu_item looks like a GtkRadioMenultem 


Deprecated 
LIMO R1 


6.71.2.3 gboolean gtk_check_menu_item_get_inconsistent (GtkCheckMenultem x 
check_menu_item) 


[deprecated] Returns the inconsistent value, That is value set by gtk_check_menu_item_set_inconsistent(). 


Parameters: 


— check_menu_item : GtkCheckMenultem 


Returns: 


TRUE if inconsistent 


Deprecated 
LIMO R1 


6.71.2.4 GtkWidget gtk_check_menu_item_new (void) 


Creates a new GtkCheckMenultem. 


Returns: 


A new widget. 


6.71.2.5 GtkWidget» gtk_check_menu_item_new_with_label (const gchar x label) 
Creates a new GtkCheckMenultem with a label. 


Parameters: 


— label : The text for the new label. 


Returns: 


A new widget. 


6.71.2.6 GtkWidget» gtk_check_menu_item_new_with_mnemonic (const gchar + label) 


[deprecated] Creates a new GtkCheckMenultem containing a label. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the menu item. 
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Parameters: 


— label : The text of the button, with an underscore in front of the mnemonic character 


Returns: 


a new GtkCheckMenultem 


Deprecated 
LIMO R1 


6.71.2.7 void gtk_check_menu_item_set_active (GtkCheckMenultem x check_menu_item, 
gboolean is_active) 


Set the active state of the menu item’s check box. 


Parameters: 


— check_menu_item,: A GtkCheckMenultem. 


— is_active : Boolean value indicating whether the check box is active. 


Returns: 


void 


6.71.2.8 void gtk_check_menu_item_set_draw_as_radio (GtkCheckMenultem = 
check_menu_item, gboolean draw_as_radio) 


[deprecated] Sets whether check_menu_item is drawn like a GtkRadioMenultem 


Parameters: 

— check_menu_item : GtkCheckMenultem 

< draw_as_radio : whether check_menu_item is drawn like a GtkRadioMenultem 
Returns: 

void 
Deprecated 

LIMO RI 


6.71.2.9 void gtk_check_menu_item_set_inconsistent (GtkCheckMenultem + check_menu_item, 
gboolean setting) 


[deprecated] If the user has selected a range of elements (such as some text or spreadsheet cells) that are 
affected by a boolean setting, and the current values in that range are inconsistent, you may want to display 
the check in an "in between" state. 


This function turns on "in between" display. Normally you would turn off the inconsistent state again if the 
user explicitly selects a setting. This has to be done manually, gtk_check_menu_item_set_inconsistent() 
only affects visual appearance, it doesn’t affect the semantics of the widget. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


656 Module Documentation 


Parameters: 
— check_menu_item : GtkCheckMenultem 


— setting : TRUE to display an "inconsistent" third state check 


Returns: 


void 
Deprecated 
LIMO R1 


6.71.2.10 void gtk_check_menu_item_toggled (GtkCheckMenultem x check_menu_item) 


Emits the GtkCheckMenultem::toggled signal. 


Parameters: 


— check_menu_item A GtkCheckMenultem. 


Returns: 


void 
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6.72 GtkRadioMenultem 


6.72.1 Detailed Description 


A radio menu item is a check menu item that belongs to a group. 
At each instant exactly one of the radio menu items from a group is selected. 


The group list does not need to be freed, as each GtkRadioMenultem will remove itself and its list item 
when it is destroyed. 


The correct way to create a group of radio menu items is approximatively this: 


Code Example: 


GtkWidget *menu; 
GtkWidget *radiomenuiteml; 
GtkWidget *radiomenuitem2; 
GtkWidget *radiomenuitem3; 
GSList *group = NULL; 


menu = gtk_menu_new(); 

radiomenuiteml = gtk_radio_menu_item_new_with_label (group, "iteml"); 

// group should be got every time a new radio menu item is added. 

group = gtk_radio_menu_item_get_group(GTK_RADIO_MENU_ITEM(radiomenuiteml)); 


radiomenuitem2 = gtk_radio_menu_item_new_with_label (group, "item2"); 
group = gtk_radio_menu_item_get_group (GTK_RADIO_MENU_ITEM (radiomenuitem2) ) ; 
radiomenuitem3 = gtk_radio_menu_item_new_with_label (group, "item3") ; 


// these two signals are both emited when the check menu item is activated, 
// so you can use only one of them. 
g_signal_connect (G_OBJECT (radiomenuiteml), "activate", 
G_CALLBACK (menuiteml_activate), NULL); 
g_signal_connect (G_OBJECT (radiomenuiteml), "toggled", 
G_CALLBACK (menuiteml_toggled), NULL); 
g_signal_connect (G_OBJECT (radiomenuiteml), "group-changed", 
G_CALLBACK (menuiteml_group_changed), NULL); 


gtk_menu_shell_append (GTK_MENU_SHELL (menu), radiomenuiteml); 
gtk_menu_shell_append (GTK_MENU_SHELL (menu), radiomenuitem2); 
gtk_menu_shell_append (GTK_MENU_SHELL (menu), radiomenuitem3); 
gtk_widget_show (menu) ; 

gtk_widget_show(radiomenuiteml); 


gtk_widget_show(radiomenuitem2); 
gtk_widget_show(radiomenuitem3); 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkRadioMenultem 


GtkRadioMenultem instance structure. 


e struct _GtkRadioMenultemClass 


GTK Native GtkRadioMenultem instance class structure. 
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Functions 


e GtkWidget * gtk_radio_menu_item_new (GSList *group) 


Creates a new GtkRadioMenultem. 


e GtkWidget * gtk_radio_menu_item_new_with_label (GSList «group, const gchar *label) 


Creates a new GtkRadioMenultem whose child is a simple GtkLabel. 


e GtkWidget * gtk_radio_menu_item_new_from_widget (GtkRadioMenultem *group) 


Creates a new GtkRadioMenultem adding it to the same group as group. 


e GtkWidget * gtk radio_menu_item_new_with_label_from_widget (GtkRadioMenultem group, 
const gchar label) 


Creates a new GtkRadioMenultem whose child is a simple GtkLabel. 


e GSList * gtk_radio_menu_item_get_group (GtkRadioMenultem *radio_menu_item) 


Returns the group to which the radio menu item belongs, as a GList of GtkRadioMenultem. 


e void gtk_radio_menu_item_set_group (GtkRadioMenultem *radio_menu_item, GSList *group) 


Sets the group of a radio menu item, or changes it. 


e GtkWidget * gtk_radio_menu_item_new_with_mnemonic (GSList «group, const gchar label) 


[Deprecated] Creates a new GtkRadioMenultem containing a label. 


e GtkWidget + gtk _radio_menu_item_new_with_mnemonic_from_widget (GtkRadioMenultem 
*group, const gchar «label) 


[Deprecated] Creates a new GtkRadioMenultem containing a label. 


6.72.2 Function Documentation 


6.72.2.1 GSListx gtk_radio_menu_item_get_group (GtkRadioMenultem x radio_menu_item) 


Returns the group to which the radio menu item belongs, as a GList of GtkRadioMenultem. 
The list belongs to GTK+ and should not be freed. 


Parameters: 


— radio_menu_item a GtkRadioMenultem. 


Returns: 


the group of radio_menu_item. 


6.72.2.2 GtkWidget» gtk_radio_menu_item_new (GSList « group) 


Creates a new GtkRadioMenultem. 


Parameters: 


— group the group to which the radio menu item is to be attached 
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Returns: 


a new GtkRadioMenultem 


6.72.2.3 GtkWidget* gtk_radio_menu_item_new_from_widget (GtkRadioMenultem * group) 
Creates a new GtkRadioMenultem adding it to the same group as group. 


Parameters: 


— group An existing GtkRadioMenultem 


Returns: 


The new GtkRadioMenultem 


6.72.2.4 GtkWidget gtk_radio_menu_item_new_with_label (GSList x group, const gchar x label) 


Creates a new GtkRadioMenultem whose child is a simple GtkLabel. 


Parameters: 


< group the group to which the radio menu item is to be attached 


< label the text for the label 


Returns: 


anew GtkRadioMenultem 


6.72.2.5 GtkWidget» gtk_radio_menu_item_new_with_label_from_widget (GtkRadioMenultem + 
group, const gchar x label) 


Creates a new GtkRadioMenultem whose child is a simple GtkLabel. 


The new GtkRadioMenultem is added to the same group as group. 


Parameters: 


< group an existing GtkRadioMenultem 
< label the text for the label 


Returns: 


The new GtkRadioMenultem 


6.72.2.6 GtkWidget» gtk_radio_menu_item_new_with_mnemonic (GSList x group, const gchar + 
label) 


[Deprecated] Creates a new GtkRadioMenultem containing a label. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the menu item. 
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Parameters: 


— group the group to which the radio menu item is to be attached 


Returns: 


a new GtkRadioMenultem 


Deprecated 
LIMO R1 


6.72.2.7 GtkWidget» gtk_radio_menu_item_new_with_mnemonic_from_widget 
(GtkRadioMenultem x group, const gchar x label) 


[Deprecated] Creates a new GtkRadioMenultem containing a label. 


The label will be created using gtk_label_new_with_mnemonic(), so underscores in label indicate the 
mnemonic for the menu item. The new GtkRadioMenultem is added to the same group as group. 


Parameters: 


— group An existing GtkRadioMenultem 


+ label the text of the button, with an underscore in front of the mnemonic character 


Returns: 


The new GtkRadioMenultem 


Deprecated 
LIMO R1 


6.72.2.8 void gtk_radio_menu_item_set_group (GtkRadioMenultem x radio_menu_item, GSList + 
group) 


Sets the group of a radio menu item, or changes it. 


Parameters: 


— radio_menu_item a GtkRadioMenultem. 


— group the new group. 


Returns: 


a new GtkRadioMenultem 
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6.73 GtkComboBox 


6.73.1 Detailed Description 


A GtkComboBox is a widget that allows the user to choose from a list of valid choices. 


The GtkComboBox displays the selected choice. When activated, the GtkComboBox displays a popup 
which allows the user to make a new choice. The style in which the selected value is displayed, and the 
style of the popup is determined by the current theme. It may be similar to a GtkOptionMenu, or similar to 
a Windows-style combo box. 


Unlike its predecessors GtkCombo and GtkOptionMenu, the GtkComboBox uses the model-view pattern; 
the list of valid choices is specified in the form of a tree model, and the display of the choices can be 
adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since 
GtkComboBox implements the GtkCellLayout interface. The tree model holding the valid choices is not 
restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure. 


In addition to the model-view API, GtkComboBox offers a simple API which is suitable for text-only 
combo boxes, and hides the complexity of managing the data in a model. It consists of the functions 
gtk_combo_box_new_text(), gtk_combo_box_append_text(), gtk_combo_box_insert_text(), gtk_combo_- 


box_prepend_text(), gtk_combo_box_remove_text() and gtk_combo_box_get_active_text(). 


Combo Box * | 


Figure 6.15: GtkComboBox 


Code Example: 


GtkWidget «combo; 

GtkCellRenderer x*renderer; 

combo = gtk_combo_box_new_with_model (model); 

g_object_unref (model); 

gtk_container_add (GTK_CONTAINER (box), combo); 

renderer = gtk_cell_renderer_pixbuf_new (); 

gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo), renderer, FALSE); 
gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo), renderer, 


"pixbuf", PIXBUF_COL, NULL); 
gtk_cell_layout_set_cell_data_func (GTK_CELL_LAYOUT (combo), 
renderer, 


set_sensitive, 
NULL, NULL); 


Data Structures 


e struct _GtkComboBox 


GtkComboBox instance structure. 


e struct _GtkComboBoxClass 
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GtkComboBox instance calss structure. 


Functions 


e GtkWidget * gtk_combo_box_new (void) 


Creates a new empty GtkComboBox. 


e GtkWidget * gtk_combo_box_new_with_model (GtkTreeModel *model) 


Creates a new GtkComboBox with the model initialized to model. 


e gint gtk_combo_box_get_wrap_width (GtkComboBox *combo_box) 


Returns the wrap width which is used to determine the number of columns for the popup menu. 


e void gtk_combo_box_set_wrap_width (GtkComboBox *combo_box, gint width) 


Sets the wrap width of combo_box to be width. 


e gint gtk_combo_box_get_row_span_column (GtkComboBox *combo_box) 


Returns the column with row span information for combo_box. 


e void gtk_combo_box_set_row_span_column (GtkComboBox *combo_box, gint row_span) 


Sets the column with row span information for combo_box to be row_span. 


e gint gtk_combo_box_get_column_span_column (GtkComboBox *combo_box) 


Returns the column with column span information for combo_box. 


e void gtk _combo_box_set_column_span_column (GtkComboBox *combo_box, gint column_- 
span) 


Sets the column with column span information for combo_box to be column_span. 


e gboolean gtk_combo_box_get_add_tearoffs (GtkComboBox *combo_box) 


Gets the current value of the :add-tearoffs property. 


e void gtk_combo_box_set_add_tearoffs (GtkComboBox *combo_box, gboolean add_tearoffs) 


Sets whether the popup menu should have a tearoff menu item. 


e G_CONST_RETURN gchar x gtk_combo_box_get_title (GtkComboBox *combo_box) 


Gets the current title of the menu in tearoff mode. 


e void gtk_combo_box_set_title (GtkComboBox *combo_box, const gchar «title) 


Sets the menu’s title in tearoff mode. 


e gboolean gtk_combo_box_get_focus_on_click (GtkComboBox *combo) 


Returns whether the combo box grabs focus when it is clicked with the mouse. 


e void gtk_combo_box_set_focus_on_click (GtkComboBox «combo, gboolean focus_on_click) 


Sets whether the combo box will grab focus when it is clicked with the mouse. 


e gint gtk_combo_box_get_active (GtkComboBox *combo_box) 


Returns the index of the currently active item, or -1 if there’s no active item. 
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e void gtk_combo_box_set_active (GtkComboBox *combo_box, gint index_) 


Sets the active item of combo_box to be the item at index. 


e gboolean gtk_combo_box_get_active_iter (GtkComboBox *combo_box, GtkTreelter xiter) 


Sets iter to point to the current active item, if it exists. 


e void gtk_combo_box_set_active_iter (GtkComboBox *combo_box, GtkTreelter xiter) 


Sets the current active item to be the one referenced by iter. 


e void gtk_combo_box_set_model (GtkComboBox *combo_box, GtkTreeModel «model) 


Sets the model used by combo_box to be model. 


e GtkTreeModel « gtk_combo_box_get_model (GtkComboBox *combo_box) 


Returns the GtkTreeModel which is acting as data source for combo_box. 


e GtkTree ViewRowSeparatorFunc gtk_combo_box_get_row_separator_func (GtkComboBox 
*combo_box) 


Returns the current row separator function. 


e void gtk_combo_box_set_row_separator_func (GtkComboBox  *combo_box, GtkTree- 
ViewRowSeparatorFunc func, gpointer data, GtkDestroyNotify destroy) 


Sets the row separator function, which is used to determine whether a row should be drawn as a separator. 


e GtkWidget * gtk_combo_box_new_text (void) 


Convenience function which constructs a new text combo box, which is a GtkComboBox just displaying 
strings. 


e void gtk_combo_box_append_text (GtkComboBox *combo_box, const gchar *text) 


Appends string to the list of strings stored in combo_box. 


e void gtk_combo_box_insert_text (GtkComboBox *combo_box, gint position, const gchar *text) 


Inserts string at position in the list of strings stored in combo_box. 


e void gtk_combo_box_prepend_text (GtkComboBox *combo_box, const gchar text) 


Prepends string to the list of strings stored in combo_box. 


e void gtk_combo_box_remove_text (GtkComboBox *combo_box, gint position) 


Removes the string at position from combo_box. 


e gchar * gtk_combo_box_get_active_text (GtkComboBox *combo_box) 


Returns the currently active string in combo_box or NULL if none is selected. 


e void gtk_combo_box_popup (GtkComboBox *combo_box) 


Pops up the menu or dropdown list of combo_box. 


e void gtk_combo_box_popdown (GtkComboBox *combo_box) 


Hides the menu or dropdown list of combo_box. 
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6.73.2 Function Documentation 


6.73.2.1 void gtk_combo_box_append_text (GtkComboBox x combo_box, const gchar = text) 


Appends string to the list of strings stored in combo_box. 


Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_- 
text(). 


Parameters: 


< combo_box A GtkComboBox 
< text A string. 


Returns: 


void 


6.73.2.2 gint gtk_combo_box_get_active (GtkComboBox * combo_box) 


Returns the index of the currently active item, or -1 if there’s no active item. 

If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this 
function returns gtk_tree_path_get_indices (path)[0], where path is the GtkTreePath of the active item. 
Parameters: 


— combo_box A GtkComboBox 


Returns: 


An integer which is the index of the currently active item, or -1 if there’s no active item. 


6.73.2.3 gboolean gtk_combo_box_get_active_iter (GtkComboBox * combo_box, GtkTreelter x 
iter) 


Sets iter to point to the current active item, if it exists. 


Parameters: 


< combo_box A GtkComboBox 


< iter The uninitialized GtkTreelter. 


Returns: 


TRUE, if iter was set 


6.73.2.4 gchar gtk_combo_box_get_active_text (GtkComboBox * combo_box) 


Returns the currently active string in combo_box or NULL if none is selected. 


Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_text() 
and with GtkComboBoxEntrys. 
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Parameters: 


— combo_box A GtkComboBox constructed with gtk_combo_box_new_text(). 


Returns: 


a newly allocated string containing the currently active text. 


6.73.2.5 gboolean gtk_combo_box_get_add_tearoffs (GtkComboBox x combo_box) 


Gets the current value of the :add-tearoffs property. 


Parameters: 


< combo_box A GtkComboBox 


Returns: 


the current value of the :add-tearoffs property 


6.73.2.6 gint gtk_combo_box_get_column_span_column (GtkComboBox x combo_box) 


Returns the column with column span information for combo_box. 


Parameters: 


— combo_box A GtkComboBox 


Returns: 


the column span column. 


6.73.2.7 gboolean gtk_combo_box_get_focus_on_click (GtkComboBox * combo) 


Returns whether the combo box grabs focus when it is clicked with the mouse. 


See gtk_combo_box_set_focus_on_click(). 


Parameters: 


< combo_box A GtkComboBox 


Returns: 


TRUE if the combo box grabs focus when it is clicked with the mouse. 


6.73.2.8 GtkTreeModelx gtk_combo_box_get_model (GtkComboBox * combo_box) 


Returns the GtkTreeModel which is acting as data source for combo_box. 


Parameters: 
< combo_box A GtkComboBox 
Returns: 


A GtkTreeModel which was passed during construction. 
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6.73.2.9 GtkTreeViewRowSeparatorFunc gtk_combo_box_get_row_separator_func 
(GtkComboBox * combo_box) 


Returns the current row separator function. 


Parameters: 


< combo_box A GtkComboBox 


Returns: 


the current row separator function. 


6.73.2.10 gint gtk_combo_box_get_row_span_column (GtkComboBox x combo_box) 


Returns the column with row span information for combo_box. 


Parameters: 


— combo_box A GtkComboBox 


Returns: 


the row span column. 


6.73.2.11 G_CONST_RETURN gchar» gtk_combo_box_get_title (GtkComboBox x combo_box) 


Gets the current title of the menu in tearoff mode. 


See gtk_combo_box_set_add_tearoffs(). 


Parameters: 


< combo_box A GtkComboBox 


Returns: 


the menu’s title in tearoff mode. This is an internal copy of the string which must not be freed. 


6.73.2.12 gint gtk_combo_box_get_wrap_width (GtkComboBox « combo_box) 


Returns the wrap width which is used to determine the number of columns for the popup menu. 


If the wrap width is larger than 1, the combo box is in table mode. 


Parameters: 


< combo_box A GtkComboBox. 


Returns: 


the wrap width. 
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6.73.2.13 void gtk_combo_box_insert_text (GtkComboBox « combo_box, gint position, const gchar 
* text) 


Inserts string at position in the list of strings stored in combo_box. 


Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_- 
text(). 


Parameters: 


— combo_box A GtkComboBox constructed using gtk_combo_box_new_text(). 


— position An index to insert text. 


< text A string. 


Returns: 


void 


6.73.2.14 GtkWidget» gtk_combo_box_new (void) 


Creates a new empty GtkComboBox. 


Returns: 


A new GtkComboBox. 


6.73.2.15 GtkWidget« gtk_combo_box_new_text (void) 


Convenience function which constructs a new text combo box, which is a GtkComboBox just displaying 
strings. 


If you use this function to create a text combo box, you should only manipulate its data source with 
the following convenience functions: gtk_combo_box_append_text(), gtk_combo_box_insert_text(), gtk_- 
combo_box_prepend_text() and gtk_combo_box_remove_text(). 


Returns: 


A new text combo box. 


6.73.2.16 GtkWidget» gtk_combo_box_new_with_model (GtkTreeModel x model) 


Creates a new GtkComboBox with the model initialized to model. 


Parameters: 


< model A GtkTreeModel. 


Returns: 


A new GtkComboBox. 
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6.73.2.17 void gtk_combo_box_popdown (GtkComboBox x combo_box) 


Hides the menu or dropdown list of combo_box. 


.This function is mostly intended for use by accessibility technologies; applications should have little use 
for it. 


Parameters: 


< combo_box A GtkComboBox 


Returns: 


void 


6.73.2.18 void gtk_combo_box_popup (GtkComboBox x combo_box) 


Pops up the menu or dropdown list of combo_box. 


This function is mostly intended for use by accessibility technologies; applications should have little use 
for it. 


Parameters: 


— combo_box A GtkComboBox constructed with gtk_combo_box_new_text() 


Returns: 


void 


6.73.2.19 void gtk_combo_box_prepend_text (GtkComboBox x combo_box, const gchar = text) 


Prepends string to the list of strings stored in combo_box. 


Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_- 
textô). 


Parameters: 


— combo_box A GtkComboBox constructed with gtk_combo_box_new_text(). 


—text A string. 


Returns: 


void 


6.73.2.20 void gtk_combo_box_remove_text (GtkComboBox x* combo_box, gint position) 


Removes the string at position from combo_box. 


Note that you can only use this function with combo boxes constructed with gtk_combo_box_new_- 
text(). 


Parameters: 


< combo_box A GtkComboBox constructed with gtk_combo_box_new_text(). 
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— position Index of the item to remove. 


Returns: 


void 


6.73.2.21 void gtk_combo_box_set_active (GtkComboBox « combo_box, gint index_) 


Sets the active item of combo_box to be the item at index. 


Parameters: 
< combo_box A GtkComboBox 


— index_ An index in the model passed during construction, or -1 to have no active item. 


Returns: 


void 


6.73.2.22 void gtk_combo_box_set_active_iter (GtkComboBox * combo_box, GtkTreelter x iter) 


Sets the current active item to be the one referenced by iter. 


iter must correspond to a path of depth one. 


Parameters: 
< combo_box A GtkComboBox 
< iter The GtkTreelter 


Returns: 


void 


6.73.2.23 void gtk_combo_box_set_add_tearoffs (GtkComboBox x* combo_box, gboolean 
add_tearoffs) 


Sets whether the popup menu should have a tearoff menu item. 


Parameters: 
— combo_box A GtkComboBox 
— add_tearoffs TRUE to add tearoff menu items 


Returns: 


void 
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6.73.2.24 void gtk_combo_box_set_column_span_column (GtkComboBox * combo_box, gint 
column_span) 


Sets the column with column span information for combo_box to be column_span. 


The column span column contains integers which indicate how many columns an item should span.. 


Parameters: 
< combo_box A GtkComboBox 


— column_span A column in the model passed during construction. 


Returns: 


void 


6.73.2.25 void gtk_combo_box_set_focus_on click (GtkComboBox x combo, gboolean 
focus_on_click) 


Sets whether the combo box will grab focus when it is clicked with the mouse. 


Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard 
focus removed from the main area of the application. 


Parameters: 
— combo_box A GtkComboBox 


— focus_on_click whether the combo box grabs focus when clicked with the mouse 


Returns: 


void 


6.73.2.26 void gtk_combo_box_set_model (GtkComboBox x combo_box, GtkTreeModel x model) 


Sets the model used by combo_box to be model. 


Will unset a previously set model (if applicable). If model is NULL, then it will unset the model. Note 
that this function does not clear the cell renderers, you have to call gtk_combo_box_cell_layout_clear() 
yourself if you need to set up different cell renderers for the new model. 


Parameters: 
< combo_box A GtkComboBox 
< model A GtkTreeModel. 


Returns: 


void 
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6.73.2.27 void gtk_combo_box_set_row_separator_func (GtkComboBox * combo_box, 
GtkTreeViewRowSeparatorFunc func, gpointer data, GtkDestroyNotify destroy) 


Sets the row separator function, which is used to determine whether a row should be drawn as a separator. 


If the row separator function is NULL, no separators are drawn. This is the default value. 


Parameters: 


— combo_box A GtkComboBox 
<— func a GtkTreeViewRowSeparatorFunc 
— data user data to pass to func, or NULL 


— destroy destroy notifier for data, or NULL 


Returns: 


void 


6.73.2.28 void gtk_combo_box_set_row_span_column (GtkComboBox « combo_box, gint 
row_span) 
Sets the column with row span information for combo_box to be row_span. 


The row span column contains integers which indicate how many rows an item should span. 


Parameters: 


< combo_box A GtkComboBox 


— row_span A column in the model passed during construction. 


Returns: 


void 


6.73.2.29 void gtk_combo_box_set_title (GtkComboBox * combo_box, const gchar x title) 


Sets the menu’s title in tearoff mode. 


Parameters: 


< combo_box A GtkComboBox 


< title a title for the menu in tearoff mode. 


Returns: 


void 


6.73.2.30 void gtk_combo_box_set_wrap_width (GtkComboBox * combo_box, gint width) 


Sets the wrap width of combo_box to be width. 


The wrap width is basically the preferred number of columns when you want the popup to be layed out in 
a table. 
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Parameters: 


< combo_box A GtkComboBox. 


— width Preferred number of columns. 


Returns: 


void 
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6.74 Layout Containers 


Modules 


GtkAspectFrame 


A frame that constrains its child to a particular aspect ratio. 


GtkAlignment 


A widget which controls the alignment and size of its child. 


¢ GtkHBox 


GtkHBox is a container that organizes child widgets into a single row. 


e GtkVBox 


GtkVBox is a container that organizes child widgets into a single column. 


e GtkFixed 
The GtkFixed widget is a container which can place child widgets at fixed positions and with fixed sizes, 
given in pixels. 

e GtkLayout 


GtkLayout is similar to GtkDrawingArea in that it's a "blank slate" and doesn’t do anything but paint a 
blank background by default. 


e GtkNoteBook 


The GtkNotebook widget is a GtkContainer whose children are pages that can be switched between using 
tab labels along one edge. 


GtkTable 


The GtkTable functions allow the programmer to arrange widgets in rows and columns, making it easy to 
align many widgets next to each other, horizontally and vertically. 
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6.75 GtkAspectFrame 


6.75.1 Detailed Description 


A frame that constrains its child to a particular aspect ratio. 


The GtkAspectFrame is useful when you want pack a widget so that it can resize but always retains the 
same aspect ratio. For instance, one might be drawing a small preview of a larger image. GtkAspectFrame 
derives from GtkFrame, so it can draw a label and a frame around the child. The frame will be "shrink- 
wrapped" to the size of the child. 


Code Example: 


GtkWidget *aspect_frame; 

GtkWidget *drawing_area; 

aspect_frame = gtk_aspect_frame_new ("2x1", 0.5, 0.5, 2, FALSE ); 
gtk_container_add (GTK_CONTAINER (window), aspect_frame) ; 
gtk_widget_show (aspect_frame) ; 

drawing_area = gtk_drawing_area_new (); 

gtk_widget_set_size_request (drawing_area, 200, 200); 
gtk_container_add (GTK_CONTAINER (aspect_frame), drawing_area) ; 
gtk_widget_show (drawing_area) ; 


Data Structures 


e struct _GtkAspectFrame 


GtkAspectFrame instance structure. 


e struct _GtkAspectFrameClass 


GtkAspectFrame instance class structure. 


Functions 


e GtkWidget x* gtk_aspect_frame_new (const gchar xlabel, gfloat xalign, gfloat yalign, gfloat ratio, 
gboolean obey_child) 


Create a new GtkAspectFrame. 


e void gtk_aspect_frame_set (GtkAspectFrame *aspect_frame, gfloat xalign, gfloat yalign, gfloat ratio, 
gboolean obey_child) 


Set parameters for an existing GtkAspectFrame. 


6.75.2 Function Documentation 


6.75.2.1 GtkWidget* gtk_aspect_frame_new (const gchar x label, gfloat xalign, gfloat yalign, gfloat 
ratio, gboolean obey_child) 


Create a new GtkAspectFrame. 


Parameters: 


< label : Label text. 
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— xalign : Horizontal alignment of the child within the allocation of the GtkAspectFrame. This 
ranges from 0.0 (left aligned) to 1.0 (right aligned) 


— yalign : Vertical alignment of the child within the allocation of the GtkAspectFrame. This ranges 
from 0.0 (left aligned) to 1.0 (right aligned) 


— ratio : The desired aspect ratio. 


— obey_child : If TRUE, ratio is ignored, and the aspect ratio is taken from the requistion of the child. 


Returns: 


the new GtkAspectFrame. 


6.75.2.2 void gtk_aspect_frame_set (GtkAspectFrame = aspect_frame, gfloat xalign, gfloat yalign, 
gfloat ratio, gboolean obey_child) 


Set parameters for an existing GtkAspectFrame. 


Parameters: 


— aspect_frame : a GtkAspectFrame 


— xalign : Horizontal alignment of the child within the allocation of the GtkAspectFrame. This 
ranges from 0.0 (left aligned) to 1.0 (right aligned) 


— yalign : Vertical alignment of the child within the allocation of the GtkAspectFrame. This ranges 
from 0.0 (left aligned) to 1.0 (right aligned) 


— ratio : The desired aspect ratio. 


— obey_child : If TRUE, ratio is ignored, and the aspect ratio is taken from the requistion of the child. 


Returns: 


void 
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6.76 GtkAlignment 


6.76.1 Detailed Description 


A widget which controls the alignment and size of its child. 


The GtkAlignment widget controls the alignment and size of its child widget. It has four settings: xscale, 
yscale, xalign, and yalign. 


The scale settings are used to specify how much the child widget should expand to fill the space allocated 
to the GtkAlignment. The values can range from 0 (meaning the child doesn’t expand at all) to 1 (meaning 
the child expands to fill all of the available space). 


The align settings are used to place the child widget within the available area. The values range from 0 (top 
or left) to 1 (bottom or right). Of course, 1f the scale settings are both set to 1, the alignment settings have 
no effect. 


Data Structures 


e struct _GtkAlignment 


GtkAlignment interface structure. 


e struct _GtkAlignmentClass 


GtkAlignment interface class structure. 


Functions 


e GType gtk_alignment_get_type (void) G_GNUC_CONST 


This Fuction returns GType. 


GtkWidget * gtk_alignment_new (gfloat xalign, gfloat yalign, gfloat xscale, gfloat yscale) 


Creates a new GtkAlignment. 


void gtk_alignment_set (GtkAlignment «alignment, gfloat xalign, gfloat yalign, gfloat xscale, gfloat 
yscale) 


Sets the GtkAlignment values. 


void gtk_alignment_set_padding (GtkAlignment *alignment, guint padding top, guint padding - 
bottom, guint padding_left, guint padding_right) 


Sets the padding on the different sides of the widget. 


void gtk_alignment_get_padding (GtkAlignment alignment, guint *padding_top, guint *padding_- 
bottom, guint «padding left, guint xpadding_right) 


Gets the padding on the different sides of the widget. 
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6.76.2 Function Documentation 


6.76.2.1 void gtk_alignment_get_padding (GtkAlignment + alignment, guint x padding_top, guint « 
padding _bottom, guint x padding _left, guint « padding_right) 
Gets the padding on the different sides of the widget. 


See gtk_alignment_set_padding(). 


Parameters: 
— alignment : a GtkAlignment. 
> padding_top : location to store the padding for the top of the widget, or NULL 
> padding_bottom : location to store the padding for the bottom of the widget, or NULL 
> padding left : location to store the padding for the left of the widget, or NULL 
> padding_right : location to store the padding for the right of the widget, or NULL 


Returns: 


void 


6.76.2.2 GType gtk_alignment_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


6.76.2.3 GtkWidget gtk_alignment_new (gfloat xalign, gfloat yalign, gfloat xscale, gfloat yscale) 


Creates a new GtkAlignment. 


Parameters: 
— xalign : the horizontal alignment of the child widget, from 0 (left) to 1 (right). 
— yalign : the vertical alignment of the child widget, from 0 (top) to 1 (bottom). 


— xscale : the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. 
A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the 
child widget will expand to fill all of the space allocated for the GtkAlignment. 


— yscale : the amount that the child widget expands vertically to fill up unused space, from 0 to 1. 
The values are similar to xscale. 
Returns: 


newly created GtkAlignment widget 
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6.76.2.4 void gtk_alignment_set (GtkAlignment + alignment, gfloat xalign, gfloat yalign, gfloat 
xscale, gfloat yscale) 


Sets the GtkAlignment values. 


Parameters: 
— alignment : a GtkAlignment. 
— xalign : the horizontal alignment of the child widget, from 0 (left) to 1 (right). 
— yalign : the vertical alignment of the child widget, from 0 (top) to 1 (bottom). 


— xscale : the amount that the child widget expands horizontally to fill up unused space, from 0 to 1. 
A value of 0 indicates that the child widget should never expand. A value of 1 indicates that the 
child widget will expand to fill all of the space allocated for the GtkAlignment. 


— yscale : the amount that the child widget expands vertically to fill up unused space, from 0 to 1. 
The values are similar to xscale. 
Returns: 


void 


6.76.2.5 void gtk_alignment_set_padding (GtkAlignment x alignment, guint padding_top, guint 
padding_bottom, guint padding_left, guint padding_right) 
Sets the padding on the different sides of the widget. 
The padding adds blank space to the sides of the widget. For instance, this can be used to indent the child 
widget towards the right by adding padding on the left. 
Parameters: 
— alignment : a GtkAlignment. 
— padding_top : the padding at the top of the widget 
— padding_bottom : the padding at the bottom of the widget 
— padding_left : the padding at the left of the widget 
— padding_right : the padding at the right of the widget. 


Returns: 


void 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.77 GtkHBox 679 


6.77 GtkHBox 


6.77.1 Detailed Description 


GtkHBox is a container that organizes child widgets into a single row. 


Use the GtkBox packing interface to determine the arrangement, spacing, width, and alignment of 
GtkHBox children. All children are allocated the same height. 


Code Example: 


GtkWidget *hbox; 
GtkWidget «button; 


hbox = gtk_hbox_new (homogeneous, spacing); 

button = gtk_button_new_with_label ("gtk_box_pack"); 
gtk_box_pack_start (GTK_BOX (hbox), button, expand, fill, padding); 
gtk_widget_show (button); 


button = gtk_button_new_with_label ("(box,"); 
gtk_box_pack_start (GTK_BOX (hbox), button, expand, fill, padding); 
gtk_widget_show (button 


r 


button = gtk_button_new_with_label (fill ? "TRUE," : "FALSE,"); 
gtk_box_pack_start (GTK_BOX (hbox), button, expand, fill, padding); 
gtk_widget_show (button); 

gtk_widget_show (hbox); 


Data Structures 


e struct _GtkHBox 


GtkHBox instance structure. 


¢ struct _GtkHBoxClass 


GtkHBox instance class structure. 


Functions 


e GtkWidget * gtk_hbox_new (gboolean homogeneous, gint spacing) 


Creates a new GtkHBox. 


6.77.2 Function Documentation 
6.77.2.1 GtkWidget gtk_hbox_new (gboolean homogeneous, gint spacing) 
Creates a new GtkHBox. 


Parameters: 


< homogeneous TRUE if all children are to be given equal space allotments. 


< spacing the number of pixels to place by default between children. 
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Returns: 


a new GtkHBox. 
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6.78 GtkVBox 


6.78.1 Detailed Description 


GtkVBox is a container that organizes child widgets into a single column. 


Use the GtkBox packing interface to determine the arrangement, spacing, height, and alignment of 
GtkVBox children. All children are allocated the same width. 


Code Example: 


GtkWidget *vbox; 
GtkWidget «button; 


vbox = gtk_vbox_new (homogeneous, spacing); 

button = gtk_button_new_with_label ("gtk_box_pack") ; 
gtk_box_pack_start (GTK_BOX (vbox), button, expand, fill, padding); 
gtk_widget_show (button); 


button = gtk_button_new_with_label ("(box,"); 
gtk_box_pack_start (GTK_BOX (vbox), button, expand, fill, padding); 
gtk_widget_show (button 


r 


button = gtk_button_new_with_label (fill ? "TRUE," : "FALSE,"); 
gtk_box_pack_start (GTK_BOX (vbox), button, expand, fill, padding); 
gtk_widget_show (button); 

gtk_widget_show (vbox); 


Data Structures 


e struct _GtkVBox 


GtkVBox instance structure. 


¢ struct _GtkVBoxClass 


GtkVBox instance class structure. 


Functions 


e GtkWidget * gtk_vbox_new (gboolean homogeneous, gint spacing) 


Creates a new GtkVBox. 


6.78.2 Function Documentation 
6.78.2.1 GtkWidget gtk_vbox_new (gboolean homogeneous, gint spacing) 
Creates a new GtkV Box. 


Parameters: 


— homogeneous TRUE if all children are to be given equal space allotments. 


— spacing the number of pixels to place by default between children. 
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Returns: 


a new GtkVBox. 
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6.79 GtkFixed 


6.79.1 Detailed Description 


The GtkFixed widget is a container which can place child widgets at fixed positions and with fixed sizes, 
given in pixels. 


GtkFixed performs no automatic layout management. 


For most applications, you should not use this container! It keeps you from having to learn about the other 
GTK+ containers, but it results in broken applications. With GtkFixed, the following things will result in 
truncated text, overlapping widgets, and other display bugs: 


Themes, which may change widget sizes. 


Fonts other than the one you used to write the app will of course change the size of widgets containing 
text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be 
using Windows or the framebuffer port of GTK+, where different fonts are available. 


Translation of text into other languages changes its size. Also, display of non-English text will use a 
different font in many cases. 


In addition, the fixed widget can’t properly be mirrored in right-to-left languages such as Hebrew and 
Arabic. That is normally GTK+ will flip the interface to put labels to the right of the thing they label, but 
it can’t do that with GtkFixed. So your application will not be usable in right-to-left languages. 


Finally, fixed positioning makes it kind of annoying to add/remove GUI elements, since you have to repo- 
sition all the other elements. This is a long-term maintenance problem for your application. 


If you know none of these things are an issue for your application, and prefer the simplicity of GtkFixed, 
by all means use the widget. But you should be aware of the tradeoffs. 


Code Example: 


GtkWidget «fixed; 
GtkWidget *button; 


fixed = gtk_fixed_new (); 
gtk_container_add (GTK_CONTAINER (window), fixed); 
gtk_widget_show (fixed); 


for (i = 1 ; i <= 3 ; i++) { 
// Creates a new button with the label "Press me" 
button = gtk_button_new_with_label ("Press me"); 


//When the button receives the "clicked" signal, it will call the 
function move_button() passing it the Fixed Container as its argument. 


g_signal_connect (G_OBJECT (button), "clicked", 
G_CALLBACK (move_button), (gpointer) fixed); 


//This packs the button into the fixed containers window. 
gtk_fixed_put (GTK_FIXED (fixed), button, i*50, i*50); 


// The final step is to display this newly created widget. 


gtk_widget_show (button); 
x} 


Data Structures 


e struct _GtkFixed 


GtkFixed instance structure. 
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e struct _GtkFixedClass 


GtkFixed instance class structure. 


Functions 


e GtkWidget * gtk_fixed_new (void) 
Creates a new GtkFixed. 


e void gtk_fixed_put (GtkFixed «fixed, GtkWidget *widget, gint x, gint y) 
Adds a widget to a GtkFixed container at the given position. 


e void gtk_fixed_move (GtkFixed «fixed, GtkWidget *widget, gint x, gint y) 


Moves a child of a GtkFixed container to the given position. 


e void gtk_fixed_set_has_window (GtkFixed x*fixed, gboolean has_window) 
Sets whether a GtkFixed widget is created with a separate GdkWindow for widget->window or not. 


e gboolean gtk_fixed_get_has_window (GtkFixed *fixed) 
Gets whether the GtkFixed has its own GdkWindow. 


6.79.2 Function Documentation 
6.79.2.1 gboolean gtk_fixed_get_has_window (GtkFixed « fixed) 
Gets whether the GtkFixed has its own GdkWindow. 
See gdk_fixed_set_has_window(). 
Parameters: 
— fixed : a GtkFixed. 


Returns: 


TRUE if fixed has its own window. 


6.79.2.2 void gtk_fixed_move (GtkFixed + fixed, GtkWidget x widget, gint x, gint y) 


Moves a child of a GtkFixed container to the given position. 


Parameters: 


— fixed : a GtkFixed. 

— widget : the child widget. 

— x : the horizontal position to move the widget to. 
— y : the vertical position to move the widget to. 


Returns: 


void 
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6.79.2.3 GtkWidget* gtk_fixed_new (void) 
Creates a new GtkFixed. 


Returns: 


a new GtkFixed widget 


6.79.2.4 void gtk_fixed_put (GtkFixed x fixed, GtkWidget « widget, gint x, gint y) 
Adds a widget to a GtkFixed container at the given position. 


Parameters: 


— fixed : a GtkFixed. 
— widget : the widget to add. 
— x : the horizontal position to place the widget at. 


— y : the vertical position to place the widget at. 


Returns: 


void 


6.79.2.5 void gtk_fixed_set_has_window (GtkFixed x fixed, gboolean has_window) 


Sets whether a GtkFixed widget is created with a separate GdkWindow for widget->window or not. 


(By default, it will be created with no separate GdkWindow). This function must be called while the 
GtkFixed is not realized, for instance, immediately after the window is created. 


This function was added to provide an easy migration path for older applications which may expect Gtk- 
Fixed to have a separate window. 
Parameters: 


— fixed : a GtkFixed. 


— has_window : TRUE if a separate window should be created 


Returns: 


void 
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6.80 GtkLayout 


6.80.1 Detailed Description 


GtkLayout is similar to GtkDrawingArea in that it’s a "blank slate" and doesn’t do anything but paint a 
blank background by default. 


It’s different in that it supports scrolling natively (you can add it to a GtkScrolledWindow), and it can 
contain child widgets, since it’s a GtkContainer. However if you’re just going to draw, a GtkDrawingArea 
is a better choice since it has lower overhead. 


When handling expose events on a GtkLayout, you must draw to GTK_LAYOUT (layout)->bin_window, 
rather than to GTK_WIDGET (layout)->window, as you would for a drawing area. 


Data Structures 


e struct _GtkLayout 


GtkLayout instance structure. 


e struct _GtkLayoutClass 


GtkLayout instance class structure. 


Functions 


e GtkWidget * gtk_layout_new (GtkAdjustment *hadjustment, GtkAdjustment *vadjustment) 


Creates a new GtkLayout. 


e void gtk_layout_put (GtkLayout «layout, GtkWidget «child_widget, gint x, gint y) 
Adds child_widget to layout, at position (x,y). 


e void gtk_layout_move (GtkLayout «layout, Gtk Widget x*child_widget, gint x, gint y) 
Adds child_widget to layout, at position (x,y). 


e void gtk_layout_set_size (GtkLayout «layout, guint width, guint height) 


Sets the size of the scrollable area of the layout. 


e void gtk_layout_get_size (GtkLayout «layout, guint «width, guint «height) 


Gets the size that has been set on the layout, and that determines the total extents of the layout’s scrollbar 
area. 


e GtkAdjustment x gtk_layout_get_hadjustment (GtkLayout *layout) 


This function should only be called after the layout has been placed in a GtkScrolledWindow or otherwise 
configured for scrolling. 


e GtkAdjustment * gtk_layout_get_vadjustment (GtkLayout *layout) 


This function should only be called after the layout has been placed in a GtkScrolledWindow or otherwise 
configured for scrolling. 


e void gtk_layout_set_hadjustment (GtkLayout «layout, GtkAdjustment x*adjustment) 


Sets the horizontal scroll adjustment for the layout. 
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e void gtk_layout_set_vadjustment (GtkLayout «layout, GtkAdjustment x*adjustment) 


Sets the horizontal scroll adjustment for the layout. 


6.80.2 Function Documentation 

6.80.2.1 GtkAdjustmentx gtk_layout_get_hadjustment (GtkLayout x layout) 

This function should only be called after the layout has been placed in a GtkScrolledWindow or otherwise 
configured for scrolling. 


It returns the GtkAdjustment used for communication between the horizontal scrollbar and layout. 


See GtkScrolled Window, GtkScrollbar, GtkAdjustment for details. 


Parameters: 


— layout a GtkLayout 


Returns: 


horizontal scroll adjustment @ remark This function should only be called after the layout has been 
placed in a GtkScrolledWindow or otherwise configured for scrolling. 


6.80.2.2 void gtk_layout_get_size (GtkLayout x layout, guint x width, guint « height) 
Gets the size that has been set on the layout, and that determines the total extents of the layout’s scrollbar 
area. 


See gtk_layout_set_size(). 


Parameters: 


— layout a GtkLayout 
— width location to store the width set on layout, or NULL 
— height location to store the height set on layout, or NULL 


Returns: 


void 


6.80.2.3 GtkAdjustmentx gtk_layout_get_vadjustment (GtkLayout « layout) 

This function should only be called after the layout has been placed in a GtkScrolledWindow or otherwise 
configured for scrolling. 

It returns the GtkAdjustment used for communication between the vertical scrollbar and layout. 


See GtkScrolledWindow, GtkScrollbar, GtkAdjustment for details. 


Parameters: 


— layout a GtkLayout 
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Returns: 


vertical scroll adjustment @ remark This function should only be called after the layout has been 
placed in a GtkScrolledWindow or otherwise configured for scrolling. 


6.80.2.4 void gtk_layout_move (GtkLayout x layout, GtkWidget « child_widget, gint x, gint y) 


Adds child_widget to layout, at position (x,y). 


layout becomes the new parent container of child_widget. 


Parameters: 


— layout a GtkLayout 
— child_widget a current child of layout 
—x X position to move to 


— y Y position to move to 


Returns: 


void 


6.80.2.5 GtkWidget» gtk_layout_new (GtkAdjustment x hadjustment, GtkAdjustment x 
vadjustment) 

Creates a new GtkLayout. 

Unless you have a specific adjustment you'd like the layout to use for scrolling, pass NULL for hadjustment 

and vadjustment. 

Parameters: 


— hadjustment horizontal scroll adjustment, or NULL 
— vadjustment vertical scroll adjustment, or NULL 


Returns: 


a new GtkLayout. 


Remarks: 


Unless you have a specific adjustment you'd like the layout to use for scrolling, pass NULL for had- 
justment and vadjustment. 


6.80.2.6 void gtk_layout_put (GtkLayout x layout, GtkWidget « child_widget, gint x, gint y) 


Adds child_widget to layout, at position (x,y). 


layout becomes the new parent container of child_widget. 


Parameters: 


— layout a GtkLayout 
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— child_widget child widget 

—x X position of child widget 

— y Y position of child widget 
Returns: 


void 


6.80.2.7 void gtk_layout_set_hadjustment (GtkLayout x layout, GtkAdjustment x adjustment) 


Sets the horizontal scroll adjustment for the layout. 


See GtkScrolledWindow, GtkScrollbar, GtkAdjustment for details. 


Parameters: 


— layout a GtkLayout 


— adjustment new horizontal scroll adjustment 


Returns: 


void 


6.80.2.8 void gtk_layout_set_size (GtkLayout x layout, guint width, guint height) 
Sets the size of the scrollable area of the layout. 


Parameters: 


— layout a GtkLayout 
— width width of entire scrollable area 


— height height of entire scrollable area 


Returns: 


void 


6.80.2.9 void gtk_layout_set_vadjustment (GtkLayout x layout, GtkAdjustment « adjustment) 


Sets the horizontal scroll adjustment for the layout. 


See GtkScrolledWindow, GtkScrollbar, GtkAdjustment for details. 


Parameters: 


— layout a GtkLayout 


— adjustment new vrtical scroll adjustment 


Returns: 


void 
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6.81 GtkNoteBook 


6.81.1 Detailed Description 


The GtkNotebook widget is a GtkContainer whose children are pages that can be switched between using 


tab labels along one edge. 


There are many configuration options for GtkNotebook. Among other things, you can choose on which 
edge the tabs appear (see gtk_notebook_set_tab_pos()), whether, if there are too many tabs to fit the noteo- 
book should be made bigger or scrolling arrows added (see gtk_notebook_set_scrollable). 


MultiPage Widget, Enhanced for the Mobile environment. 


Add Frame 2 


Figure 6.16: GtkNotebook 


Code Example: 


form = gtk_form_new() 
GtkNotebook «notebook; 
notebook = gtk_notebook_new_with_tab_style(style) ; 


gint gtk_notebook_append_page_with_tab_image ( 
notebook, 

child, 

tab_label, 

tab_image 

i 
gtk_form_contain_add(form, notebook); 
gtk_widget_show (form); 
gtk_widget_show (notebook) ; 
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Modified for 
LIMO RI 


Data Structures 


e struct _GtkNotebook 


GtkNotebook instance structure. 


struct _GtkNotebookClass 


GtkNotebook instance class structure. 


Enumerations 


enum GtkNotebookTabStyle { 


RIGHT_ARRANGED_TAB, NORMAL_SINGLE_TAB 
NOTEBOOK_TAB_NORMAL, 


NOTEBOOK_TAB_DATA_WHEEL } 


enum for a tab style this enum decides a behavior of the rendering related function. 


, NOTEBOOK_TAB_INACTIVATE, 


Functions 


GtkWidget * gtk_notebook_new (void) 


Creates a new GtkNotebook widget with no pages. 


GtkWidget * gtk_notebook_new_with_tab_style (GtkNotebookTabStyle tabStyle) 


Creates a new GtkNotebook widget with no pages. 


void gtk_notebook_set_tab_style (GtkNotebook «notebook, GtkNotebookTabStyle tabStyle) 
Sets the Notebook Tab style. 


GtkNotebookTabStyle gtk_notebook_get_tab_style (GtkNotebook *notebook) 


Returns the current Notebook Tab style. 


gint gtk_notebook_append_page_with_tab_image (GtkNotebook x*notebook, GtkWidget child, 
GtkWidget *tab_label, GtkWidget *tab_image) 


Appends a page to notebook with Image to display in the tab title. 


gint gtk _notebook_append_page (GtkNotebook notebook, GtkWidget *child, GtkWidget x*tab_- 
label) 


Appends a page to notebook. 


gint gtk_notebook_append_page_menu (GtkNotebook *notebook, GtkWidget *child, GtkWidget 
*tab_label, GtkWidget *menu_label) 


Appends a page to notebook, specifying the widget to use as the label in the popup menu. 


gint gtk_notebook_prepend_page_with_tab_image (GtkNotebook «notebook, GtkWidget child, 
GtkWidget *tab_label, GtkWidget *tab_image) 
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prepends a page to notebook with Image to display in the Tab title 


gint gtk_notebook_prepend_page (GtkNotebook *notebook, GtkWidget *child, GtkWidget x*tab_- 
label) 


prepends a page to notebook. 


gint gtk_notebook_prepend_page_menu (GtkNotebook «notebook, GtkWidget *child, GtkWidget 
*tab_label, GtkWidget *«menu_label) 


Prepends a page to notebook, specifying the widget to use as the label in the popup menu. 


gint gtk_notebook_insert_page_with_tab_image (GtkNotebook notebook, GtkWidget «child, Gtk- 
Widget x*page_tab_label, GtkWidget *page_tab_image, gint position) 


Insert a page into notebook at the given position. 


gint gtk_notebook_insert_page (GtkNotebook «notebook, GtkWidget «child, GtkWidget *page_- 
tab_label, gint position) 


Insert a page into notebook at the given position. 


gint gtk_notebook_insert_page_menu (GtkNotebook «notebook, GtkWidget child, GtkWidget 
*tab_label, GtkWidget *«menu_label, gint position) 


Insert a page into notebook at the given position, specifying the widget to use as the label in the popup 
menu. 


void gtk_notebook_remove_page (GtkNotebook «notebook, gint page_num) 


Removes a page from the notebook given its index in the notebook. 


void gtk_notebook_set_window_creation_hook (GtkNotebook WindowCreationFunc func, gpointer 
data, GDestroyNotify destroy) 


Installs a global function used to create a window when a detached tab is dropped in an empty area. 


void gtk_notebook_set_group_id (GtkNotebook notebook, gint group_id) 


[Deprecated] Sets an group identificator for notebook, notebooks sharing the same group identificator will 
be able to exchange tabs via drag and drop. 


gint gtk_notebook_get_group_id (GtkNotebook *notebook) 


[Deprecated] Gets the current group identificator for notebook. 


gint gtk_notebook_get_current_page (GtkNotebook *notebook) 


Returns the page number of the current page. 


GtkWidget * gtk_notebook_get_nth_page (GtkNotebook *notebook, gint page_num) 


Returns the child widget contained in page number page_num. 


gint gtk_notebook_get_n_pages (GtkNotebook *notebook) 


Gets the number of pages in a notebook. 


gint gtk_notebook_page_num (GtkNotebook «notebook, GtkWidget *child) 


Finds the index of the page which contains the given child widget. 


void gtk_notebook_set_current_page (GtkNotebook «notebook, gint page_num) 


Switches to the page number page_num. 
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e void gtk_notebook_next_page (GtkNotebook *notebook) 


Switches to the next page. 


e void gtk_notebook_prev_page (GtkNotebook *notebook) 


Switches to the prev page. 


e void gtk_notebook_set_show_border (GtkNotebook «notebook, gboolean show_border) 


Sets whether a bevel will be drawn around the notebook pages. 


e gboolean gtk_notebook_get_show_border (GtkNotebook *notebook) 


Returns whether a bevel will be drawn around the notebook pages. 


e void gtk_notebook_set_show_tabs (GtkNotebook «notebook, gboolean show_tabs) 


Sets whether to show the tabs for the notebook or not. 


e gboolean gtk_notebook_get_show_tabs (GtkNotebook notebook) 


Returns whether the tabs of the notebook are shown. 


e void gtk_notebook_set_tab_pos (GtkNotebook «notebook, GtkPositionType pos) 


Sets the edge at which the tabs for switching pages in the notebook are drawn. 


e GtkPositionType gtk_notebook_get_tab_pos (GtkNotebook notebook) 


Gets the edge at which the tabs for switching pages in the notebook are drawn. 


e void gtk_notebook_set_scrollable (GtkNotebook «notebook, gboolean scrollable) 


Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area. 


e gboolean gtk_notebook_get_scrollable (GtkNotebook *notebook) 


Returns whether the tab label area has arrows for scrolling. 


e void gtk_notebook_popup_enable (GtkNotebook *notebook) 


[Deprecated] Enables the popup menu: if the user clicks with the right mouse button on the bookmarks, a 
menu with all the pages will be popped up. 


e void gtk_notebook_popup_disable (GtkNotebook *notebook) 
[Deprecated] Disables the popup menu. 


e GtkWidget * gtk_notebook_get_tab_label (GtkNotebook «notebook, GtkWidget child) 
Returns the tab label widget for the page child. 


e void gtk_notebook_set_tab_label (GtkNotebook «notebook, GtkWidget «child, GtkWidget x*tab_- 
label) 


Changes the tab label for child. 


e void gtk_notebook_set_tab_label_text (GtkNotebook *notebook, GtkWidget «child, const gchar 
*tab_text) 


Creates a new label and sets it as the tab label for the page containing child. 


e G_CONST_RETURN gchar * gtk_notebook_get_tab_label_text (GtkNotebook *notebook, Gtk- 
Widget x*child) 
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Retrieves the text of the tab label for the page containing child. 


GtkWidget * gtk_notebook_get_menu_label (GtkNotebook «notebook, GtkWidget *child) 


Retrieves the menu label widget of the page containing child. 


void gtk_notebook_set_menu_label (GtkNotebook notebook, GtkWidget child, GtkWidget 
*menu_label) 


Changes the menu label for the page containing child. 


void gtk_notebook_set_menu_label_text (GtkNotebook *notebook, GtkWidget «child, const gchar 
*menu_text) 


Creates a new label and sets it as the menu label of child. 


G_CONST_RETURN gchar x gtk_notebook_get_menu_label_text (GtkNotebook «notebook, Gtk- 
Widget «child) 


Retrieves the text of the tab label for the page containing child. 


void gtk_notebook_query_tab_label_packing (GtkNotebook notebook, GtkWidget child, 
gboolean «expand, gboolean «fill, GtkPackType «pack_type) 


Query the packing attributes for the tab label of the page containing child. 


void gtk_notebook_set_tab_label_packing (GtkNotebook *notebook, GtkWidget *child, gboolean 
expand, gboolean fill, GtkPackType pack_type) 


Sets the packing parameters for the tab label of the page containing child. 


void gtk_notebook_reorder_child (GtkNotebook «notebook, GtkWidget «child, gint position) 


Reorders the page containing child, so that it appears in position position. 


gboolean gtk_notebook_get_tab_reorderable (GtkNotebook «notebook, GtkWidget *child) 


Gets whether the tab can be reordered via drag and drop or not. 


void gtk_notebook_set_tab_reorderable (GtkNotebook «notebook, GtkWidget «child, gboolean re- 
orderable) 


Sets whether the notebook tab can be reordered via drag and drop or not. 


gboolean gtk_notebook_get_tab_detachable (GtkNotebook «notebook, GtkWidget *child) 


Returns whether the tab contents can be detached from notebook. 


void gtk_notebook_set_tab_detachable (GtkNotebook *notebook, GtkWidget «child, gboolean de- 
tachable) 


Sets whether the tab can be detached from notebook to another notebook or widget. 


void gtk_notebook_set_tab_image (GtkNotebook »*notebook, GtkWidget xchild, GtkWidget 
*image) 


Sets an image to the notebook. 


GtkWidget * gtk_notebook_get_tab_image (GtkNotebook «notebook, GtkWidget *child) 


Gets an image from the notebook. 
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6.81.2 Enumeration Type Documentation 
6.81.2.1 enum GtkNotebookTabStyle 


enum for a tab style this enum decides a behavior of the rendering related function. 


this enum decides a behavior of the rendering related function. 


Enumerator: 
RIGHT_ARRANGED_TAB tabs arranged on the right . 
. || label ||tab|tab|tab]..|| it is similar to normal_tab but only one tab is shown. || label || 
NORMAL_SINGLE_TAB util tab can have a label or an image or both. 
. || tab | tab | tab |.. || 
NOTEBOOK_TAB_INACTIVATE No tab item. 
NOTEBOOK_TAB_NORMAL normal tab style - left arranged tab 
NOTEBOOK_TAB_DATA_WHEEL similer to SINGLE_SHOWN_TAB 


6.81.3 Function Documentation 


6.81.3.1 gint gtk_notebook_append_page (GtkNotebook x notebook, GtkWidget « child, 
GtkWidget x tab_label) 


Appends a page to notebook. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] the GtkWidget to use as the contents of the page.. 


tab_label [in] the GtkWidget to be used as the label for the page, or NULL to use the default label, 
"page N’. 


Returns: 


the index (starting from 0) of the appended page in the notebook, or -1 if function fails 


6.81.3.2 gint gtk_notebook_append_page_menu (GtkNotebook x notebook, GtkWidget x child, 
GtkWidget « tab_label, GtkWidget x menu_label) 


Appends a page to notebook, specifying the widget to use as the label in the popup menu. 


Parameters: 


notebook [in] GtkNotebook widget. 

child [in] the GtkWidget to use as the contents of the page.. 

tab_label [in] the GtkWidget to be used as the label for the page, or NULL to use the default label, 
"page N’. 

menu_label [in] the widget to use as a label for the page-switch menu, if that is enabled. If NULL, 
and tab_label is a GtkLabel or NULL, then the menu label will be a newly created label with 
the same text as tab_label; If tab_label is not a GtkLabel, menu_label must be specified if the 
page-switch menu is to be used. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


696 Module Documentation 


Returns: 


the index (starting from 0) of the appended page in the notebook, or -1 if function fails 


6.81.3.3 gint gtk_notebook_append_page_with_tab_image (GtkNotebook « notebook, GtkWidget 
x child, GtkWidget « tab_label, GtkWidget x tab_image) 


Appends a page to notebook with Image to display in the tab title. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] list widget contained to gtknotebook widget. 
tab_label [in] label widget contained to hbox. 


tab_image [in] image widget contained to hbox. 


Returns: 


the index (starting from 0) of the appended page in the notebook, or -1 if function fails. 


Since 


LIMO RI 


6.81.3.4 gint gtk_notebook_get_current_page (GtkNotebook « notebook) 
Returns the page number of the current page. 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 
will be returned. 


6.81.3.5 gint gtk_notebook_get_group_id (GtkNotebook « notebook) 
[Deprecated] Gets the current group identificator for notebook. 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


the group identificator, or -1 if none is set. 


Deprecated 
LIMO R1 
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6.81.3.6 GtkWidget gtk_notebook_get_menu_label (GtkNotebook x notebook, GtkWidget x child) 


Retrieves the menu label widget of the page containing child. 


Parameters: 

notebook [in] GtkNotebook widget. 

child [in] a widget contained in a page of notebook 
Returns: 


the menu label, or NULL if the notebook page does not have a menu label other than the default (the 
tab label). 


6.81.3.7 G_CONST_RETURN gchar» gtk_notebook_get_menu_label_text (GtkNotebook + 
notebook, GtkWidget « child) 


Retrieves the text of the tab label for the page containing child. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] the child widget of a page of the notebook. 


Returns: 


value: the text of the tab label, or NULL if the widget does not have a menu label other than the default 
menu label, or the menu label widget is not a GtkLabel. The string is owned by the widget and must 
not be freed. 


6.81.3.8 gint gtk_notebook_get_n_pages (GtkNotebook + notebook) 


Gets the number of pages in a notebook. 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


the number of pages in the notebook. 


6.81.3.9 GtkWidget* gtk_notebook_get_nth_ page (GtkNotebook x notebook, gint page_num) 


Returns the child widget contained in page number page_num. 


Parameters: 

notebook [in] GtkNotebook widget. 

page_num [in] the index of a page in the noteobok, or -1 to get the last page. 
Returns: 


the child widget, or NULL if page_num is out of bounds. 
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6.81.3.10 gboolean gtk_notebook_get_scrollable (GtkNotebook « notebook) 


Returns whether the tab label area has arrows for scrolling. 


See gtk_notebook_set_scrollable(). 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


TRUE if arrows for scrolling are present 


6.81.3.11 gboolean gtk_notebook_get_show_border (GtkNotebook + notebook) 


Returns whether a bevel will be drawn around the notebook pages. 


See gtk_notebook_set_show_border(). 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


TRUE if the bevel is drawn 


6.81.3.12 gboolean gtk_notebook_get_show_tabs (GtkNotebook x notebook) 


Returns whether the tabs of the notebook are shown. 
See gtk_notebook_set_show_tabs(). 
Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


TRUE if the tabs are shown 


6.81.3.13 gboolean gtk_notebook_get_tab_detachable (GtkNotebook x notebook, GtkWidget x 
child) 


Returns whether the tab contents can be detached from notebook. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] a child GtkWidget 
Returns: 


TRUE if the tab is detachable. 
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6.81.3.14 GtkWidgetx* gtk_notebook_get_tab_image (GtkNotebook x notebook, GtkWidget x child) 


Gets an image from the notebook. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] the page 


Returns: 


image image widget 


Since 


LIMO RI 


6.81.3.15 GtkWidget» gtk_notebook_get_tab_label (GtkNotebook « notebook, GtkWidget x child) 


Returns the tab label widget for the page child. 


NULL is returned if child is not in notebook or if no tab label has specifically been set for child. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] the page 


Returns: 


the tab label 


6.81.3.16 G_CONST_RETURN gchar» gtk_notebook_get_tab_label_text (GtkNotebook + 
notebook, GtkWidget * child) 


Retrieves the text of the tab label for the page containing child. 


Parameters: 
notebook [in] GtkNotebook widget. 


child [in] a widget contained in a page of notebook 


Returns: 


value: the text of the tab label, or NULL if the tab label widget is not a GtkLabel. The string is owned 
by the widget and must not be freed. 


6.81.3.17 GtkPositionType gtk_notebook_get_tab_pos (GtkNotebook + notebook) 


Gets the edge at which the tabs for switching pages in the notebook are drawn. 
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Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


the edge at which the tabs are drawn 


6.81.3.18 gboolean gtk_notebook_get_tab_reorderable (GtkNotebook + notebook, GtkWidget + 
child) 


Gets whether the tab can be reordered via drag and drop or not. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] a child GtkWidget 
Returns: 


TRUE if the tab is reorderable. 


6.81.3.19 GtkNotebookTabStyle gtk_notebook_get_tab_style (GtkNotebook « notebook) 
Returns the current Notebook Tab style. 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


Returns the Tab style of the Notebook. a GtkNotebookTabStyle. 


Since 


LIMO R1 


6.81.3.20 gint gtk_notebook_insert_page (GtkNotebook x notebook, GtkWidget « child, 
GtkWidget x page_tab_label, gint position) 


Insert a page into notebook at the given position. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] list widget contained to gtknotebook widget. 
page_tab_label [in] label widget contained to hbox. 


position [in] the index (starting at 0) at which to insert the page, or -1 to append the page after all 
other pages. 


Returns: 


the index (starting from 0) of the appended page in the notebook, or -1 if function fails. 
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6.81.3.21 gint gtk_notebook_insert_page_menu (GtkNotebook x notebook, GtkWidget x child, 
GtkWidget x tab_label, Gtk Widget x menu_label, gint position) 


Insert a page into notebook at the given position, specifying the widget to use as the label in the popup 
menu. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] list widget contained to gtknotebook widget. 
tab_label label [in] widget contained to hbox. 


menu_label [in] the widget to use as a label for the page-switch menu, if that is enabled. If NULL, 
and tab_label is a GtkLabel or NULL, then the menu label will be a newly created label with 
the same text as tab_label; If tab_label is not a GtkLabel, menu_label must be specified if the 
page-switch menu is to be used. 


— position the index (starting at 0) at which to insert the page, or -1 to append the page after all other 
pages. 
Returns: 


the index (starting from 0) of the appended page in the notebook, or -1 1f function fails. 


6.81.3.22 gint gtk_notebook_insert_page_with_tab_image (GtkNotebook « notebook, GtkWidget x 
child, Gtk Widget x* page_tab_label, GtkWidget x page_tab_image, gint position) 


Insert a page into notebook at the given position. 


Supports Image to display int he Tab Title 


Parameters: 


notebook [in] GtkNotebook widget. 

child [in] list widget contained to gtknotebook widget. 
page_tab_label [in] label widget contained to hbox. 
page _tab_image [in] image widget contained to hbox. 


position [in] the index (starting at 0) at which to insert the page, or -1 to append the page after all 
other pages. 


Returns: 


the index (starting from 0) of the appended page in the notebook, or -1 if function fails. 


Since 


LIMO RI 


6.81.3.23 GtkWidget» gtk_notebook_new (void) 


Creates a new GtkNotebook widget with no pages. 


Returns: 


the newly created GtkNotebook 
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6.81.3.24 GtkWidget« gtk_notebook_new_with_tab_style (GtkNotebookTabStyle tabStyle) 


Creates a new GtkNotebook widget with no pages. 


Parameters: 


tabStyle [in] a GtkNotebookTabStyle 


Returns: 


the newly created GtkNotebook 


Since 


LIMO R1 


6.81.3.25 void gtk_notebook_next_page (GtkNotebook x notebook) 
Switches to the next page. 
Nothing happens if the current page is the last page. 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


void 


6.81.3.26 gint gtk_notebook_page_num (GtkNotebook x notebook, GtkWidget « child) 


Finds the index of the page which contains the given child widget. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] list widget contained to gtknotebook widget. 


Returns: 


the index of the page containing child, or -1 if child is not in the notebook. 


6.81.3.27 void gtk_notebook_popup_disable (GtkNotebook + notebook) 


[Deprecated] Disables the popup menu. 
Parameters: 

notebook [in] GtkNotebook widget. 
Returns: 

void 
Deprecated 

LIMO R1 
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6.81.3.28 void gtk_notebook_popup_enable (GtkNotebook x notebook) 


[Deprecated] Enables the popup menu: if the user clicks with the right mouse button on the bookmarks, a 
menu with all the pages will be popped up. 
Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


void 
Deprecated 
LIMO R1 


6.81.3.29 gint gtk_notebook_prepend_page (GtkNotebook x notebook, GtkWidget « child, 
GtkWidget x tab_label) 


prepends a page to notebook. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] list widget contained to gtknotebook widget. 


tab_label [in] the GtkWidget to be used as the label for the page, or NULL to use the default label, 
"page N’. 


Returns: 


the index (starting from 0) of the prepended page in the notebook, or -1 if function fails 


6.81.3.30 gint gtk_notebook_prepend_page_menu (GtkNotebook x notebook, GtkWidget x child, 
GtkWidget x tab_label, Gtk Widget * menu_label) 


Prepends a page to notebook, specifying the widget to use as the label in the popup menu. 


Parameters: 


notebook [in] GtkNotebook widget. 

child [in] list widget contained to gtknotebook widget. 

tab_label [in] the GtkWidget to be used as the label for the page, or NULL to use the default label, 
"page N’. 

menu_label [in] the widget to use as a label for the page-switch menu, if that is enabled. If NULL, 
and tab_label is a GtkLabel or NULL, then the menu label will be a newly created label with 
the same text as tab_label; If tab_label is not a GtkLabel, menu_label must be specified if the 
page-switch menu is to be used. 


Returns: 


the index (starting from 0) of the prepended page in the notebook, or -1 if function fails 
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6.81.3.31 gint gtk_notebook_prepend_page_with_tab_image (GtkNotebook * notebook, 
GtkWidget x child, GtkWidget « tab_label, GtkWidget « tab_image) 


prepends a page to notebook with Image to display in the Tab title 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] list widget contained to gtknotebook widget. 
tab_label [in] label widget contained to hbox. 


tab_image [in] image widget contained to hbox. 


Returns: 


the index (starting from 0) of the appended page in the notebook, or -1 if function fails. 


Since 


LIMO RI 


6.81.3.32 void gtk_notebook_prev_page (GtkNotebook x notebook) 


Switches to the prev page. 


Nothing happens if the current page is the first page. 


Parameters: 


notebook [in] GtkNotebook widget. 


Returns: 


void 


6.81.3.33 void gtk_notebook_query_tab_label_packing (GtkNotebook x notebook, GtkWidget x 
child, gboolean x expand, gboolean « fill, GtkPackType « pack_type) 


Query the packing attributes for the tab label of the page containing child. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] the page 
expand [in] location to store the expand value (or NULL) 
fill [in] location to store the fill value (or NULL) 
pack_type [in] location to store the pack_type (or NULL) 


Returns: 


void 
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6.81.3.34 void gtk_notebook_remove_page (GtkNotebook x notebook, gint page_num) 
Removes a page from the notebook given its index in the notebook. 


Parameters: 


notebook [in] GtkNotebook widget. 


page_num [in] the index of a notebook page, starting from 0. If -1, the last page will be removed. 


Returns: 


void 


6.81.3.35 void gtk_notebook_reorder_child (GtkNotebook x notebook, GtkWidget x child, gint 
position) 
Reorders the page containing child, so that it appears in position position. 


If position is greater than or equal to the number of children in the list or negative, child will be moved to 
the end of the list. 


Parameters: 


notebook [in] GtkNotebook widget. 
child[in] the child to move 


position [in] the new position, or -1 to move to the end 


Returns: 


void 


6.81.3.36 void gtk_notebook_set_current_page (GtkNotebook x notebook, gint page_num) 
Switches to the page number page_num. 


Parameters: 


notebook [in] GtkNotebook widget. 


page_num [in] index of the page to switch to, starting from 0. If negative, the last page will be used. 
If greater than the number of pages in the notebook, nothing will be done. 


Returns: 


void 


6.81.3.37 void gtk_notebook_set_group_id (GtkNotebook x notebook, gint group_id) 


[Deprecated] Sets an group identificator for notebook, notebooks sharing the same group identificator will 
be able to exchange tabs via drag and drop. 


A notebook with group identificator -1 will not be able to exchange tabs with any other notebook. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


706 Module Documentation 


Parameters: 


notebook [in] GtkNotebook widget. 

group_id [in] a group identificator, or -1 to unset it 
Returns: 

void 
Deprecated 

LIMO RI 


6.81.3.38 void gtk_notebook_set_menu_label (GtkNotebook x notebook, GtkWidget x child, 
GtkWidget x menu_label) 


Changes the menu label for the page containing child. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] the child widget 
menu_label [in] the menu label, or NULL for default 


Returns: 


void 


6.81.3.39 void gtk_notebook_set_menu_label_text (GtkNotebook * notebook, GtkWidget * child, 
const gchar x menu_text) 


Creates a new label and sets it as the menu label of child. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] the child widget 


menu_text [in] the label text 


Returns: 


void 


6.81.3.40 void gtk_notebook_set_scrollable (GtkNotebook x notebook, gboolean scrollable) 
Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area. 


Parameters: 


notebook [in] GtkNotebook widget. 
scrollable [in] TRUE if scroll arrows should be added 
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6.81.3.41 void gtk_notebook_set_show_border (GtkNotebook « notebook, gboolean show_border) 


Sets whether a bevel will be drawn around the notebook pages. 


This only has a visual effect when the tabs are not shown. See gtk_notebook_set_show_tabs(). 


Parameters: 


notebook [in] GtkNotebook widget. 
show_border [in] TRUE if a bevel should be drawn around the notebook. 


Returns: 


void 


See also: 


gtk_notebook_set_show_tabs() 


6.81.3.42 void gtk_notebook_set_show_tabs (GtkNotebook x notebook, gboolean show_tabs) 


Sets whether to show the tabs for the notebook or not. 


Parameters: 


notebook [in] GtkNotebook widget. 
show_tabs [in] TRUE if the tabs should be shown. 


Returns: 


void 


6.81.3.43 void gtk_notebook_set_tab_detachable (GtkNotebook x notebook, GtkWidget x child, 
gboolean detachable) 


Sets whether the tab can be detached from notebook to another notebook or widget. 


Note that 2 notebooks must share a common group identificator (see gtk_notebook_set_group_id()) to 
allow automatic tabs interchange between them. 


If you want a widget to interact with a notebook through DnD (..e.: accept dragged tabs from it) it must 
be set as a drop destination and accept the target "GTK_NOTEBOOK_TAB". The notebook will fill the 
selection with a GtkWidget*x* pointing to the child widget that corresponds to the dropped tab. 


static void 


on_drop_zone_drag_data_received (GtkWidget xwidget, 
GdkDragContext *context, 
gint xX, 
gint Yr 
GtkSelectionData *selection_data, 
guint info, 
guint time, 
gpointer user_data) 


{ 
GtkWidget «notebook; 
GtkWidget *x*child; 
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notebook = gtk_drag_get_source_widget (context); 
child = (voidx*) selection_data->data; 


process_widget (x*child); 
gtk_container_remove (GTK_CONTAINER (notebook), *child); 


If you want a notebook to accept drags from other widgets, you will have to set your own DnD code to do 
it. 


Parameters: 

notebook [in] GtkNotebook widget. 

child [in] a child GtkWidget 

detachable [in] whether the tab is detachable or not 
Returns: 


void 


6.81.3.44 void gtk_notebook_set_tab_image (GtkNotebook « notebook, GtkWidget x child, 
GtkWidget x image) 


Sets an image to the notebook. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] the page 

Returns: 
void 

Since 


LIMO R1 


6.81.3.45 void gtk_notebook_set_tab_label (GtkNotebook x notebook, GtkWidget x child, 
GtkWidget x tab_label) 

Changes the tab label for child. 

If NULL is specified for tab_label, then the page will have the label "page N’. 


Parameters: 


notebook [in] GtkNotebook widget. 
child [in] the page 
tab_label [in] the tab label widget to use, or NULL for default tab label. 


Returns: 


void 
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6.81.3.46 void gtk_notebook_set_tab_label_packing (GtkNotebook x notebook, GtkWidget * child, 
gboolean expand, gboolean fill, GtkPackType pack_type) 
Sets the packing parameters for the tab label of the page containing child. 


See gtk_box_pack_start() for the exact meaning of the parameters. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] the child widget 
expand [in] whether to expand the bookmark or not 
fill [in] whether the bookmark should fill the allocated area or not 


pack_type [in] the position of the bookmark 


Returns: 


void 


6.81.3.47 void gtk_notebook_set_tab_label_text (GtkNotebook « notebook, GtkWidget « child, 
const gchar x tab_text) 


Creates a new label and sets it as the tab label for the page containing child. 


Parameters: 
notebook [in] GtkNotebook widget. 
child [in] the page 


tab_text [in] the label text 


Returns: 


void 


6.81.3.48 void gtk_notebook_set_tab_pos (GtkNotebook x notebook, GtkPositionType pos) 
Sets the edge at which the tabs for switching pages in the notebook are drawn. 
Parameters: 


notebook [in] GtkNotebook widget. 


pos [in] the edge to draw the tabs at. 


Returns: 


void 
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6.81.3.49 void gtk_notebook_set_tab_reorderable (GtkNotebook x notebook, GtkWidget x child, 
gboolean reorderable) 


Sets whether the notebook tab can be reordered via drag and drop or not. 


Parameters: 
— notebook GtkNotebook widget. 
— child a child GtkWidget 


— child whether the tab is reorderable or not. 


Returns: 


void 


6.81.3.50 void gtk_notebook_set_tab_style (GtkNotebook « notebook, GtkNotebookTabStyle 
tabStyle) 


Sets the Notebook Tab style. 


Parameters: 


notebook [in] GtkNotebook widget. 
tabStyle [in] a GtkNotebookTabStyle 


Returns: 


void 


Since 


LIMO R1 


6.81.3.51 void gtk_notebook_set_window_creation_hook (GtkNotebookWindowCreationFunc 
func, gpointer data, GDestroyNotify destroy) 


Installs a global function used to create a window when a detached tab is dropped in an empty area. 


Parameters: 


func [in] the GtkNotebookWindowCreationFunc, or NULL 
data [in] user data for func 


destroy [in] Destroy notifier for data, or NULL 


Returns: 


void 
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6.82 GtkTable 


6.82.1 Detailed Description 


The GtkTable functions allow the programmer to arrange widgets in rows and columns, making it easy to 
align many widgets next to each other, horizontally and vertically. 


Tables are created with a call to gtk_table_new(), the size of which can later be changed with gtk_table_- 
resize(). 


Widgets can be added to a table using gtk_table_attach() or the more convenient (but slightly less flexible) 
gtk_table_attach_defaults(). 


To alter the space next to a specific row, use gtk_table_set_row_spacing(), and for a column, gtk_table_- 
set_col_spacing(). 


The gaps between all rows or columns can be changed by calling gtk_table_set_row_spacings() or gtk_- 
table_set_col_spacings() respectively. 


gtk_table_set_homogeneous(), can be used to set whether all cells in the table will resize themselves to the 
size of the largest widget in the table. 


Code Example: 


GtkWidget «table; 
GtkWidget «button; 


table = gtk_table_new (2, 2, TRUE); 
gtk_container_add (GTK_CONTAINER (window), table); 


button = gtk_button_new_with_label ("button 1"); 

g_signal_connect (G_OBJECT (button), "clicked", 

G_CALLBACK (callback), (gpointer) "button 1"); 
gtk_table_attach_defaults (GTK_TABLE (table), button, 0, 1, 0, 1); 
gtk_widget_show (button); 


button = gtk_button_new_with_label ("button 2"); 

g_signal_connect (G_OBJECT (button), "clicked", 

G_CALLBACK (callback), (gpointer) "button 2"); 
gtk_table_attach_defaults (GTK_TABLE (table), button, 1, 2, 0, 1); 
gtk_widget_show (button); 


button = gtk_button_new_with_label ("Quit"); 

g_signal_connect (G_OBJECT (button), "clicked", 

G_CALLBACK (delete_event), NULL); 
gtk_table_attach_defaults (GTK_TABLE (table), button, 0, 2, 1, 2); 
gtk_widget_show (button); 

gtk_widget_show (table); 


Data Structures 


e struct _GtkTable 


GtkTable instance class structure. 


e struct _GtkTableClass 


GtkTable instance class structure. 
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Functions 


e GtkWidget x gtk_table_new (guint rows, guint columns, gboolean homogeneous) 


Used to create a new table widget. 


e void gtk_table_resize (GtkTable «table, guint rows, guint columns) 


If you need to change a table’s size after it has been created, this function allows you to do so. 


e void gtk_table_attach (GtkTable x*table, Gtk Widget «child, guint left_attach, guint right_attach, guint 
top_attach, guint bottom_attach, GtkAttachOptions xoptions, GtkAttachOptions yoptions, guint 
xpadding, guint ypadding) 


Adds a widget to a table. 


e void gtk_table_attach_defaults (GtkTable table, GtkWidget «widget, guint left_attach, guint right_- 
attach, guint top_attach, guint bottom_attach) 


As there are many options associated with gtk_table_attach(), this convenience function provides the pro- 
grammer with a means to add children to a table with identical padding and expansion options. 


e void gtk_table_set_row_spacing (GtkTable table, guint row, guint spacing) 


Changes the space between a given table row and the subsequent row. 


e guint gtk_table_get_row_spacing (GtkTable «table, guint row) 


Gets the amount of space between row row, and row row + 1. 


e void gtk_table_set_col_spacing (GtkTable «table, guint column, guint spacing) 


Alters the amount of space between a given table column and the following column. 


e guint gtk _table_get_col_spacing (GtkTable *table, guint column) 


Gets the amount of space between column col, and column col + 1. 


e void gtk_table_set_row_spacings (GtkTable xtable, guint spacing) 


Sets the space between every row in table equal to spacing. 


e guint gtk _table_get_default_row_spacing (GtkTable «table) 


Gets the default row spacing for the table. 


e void gtk_table_set_col_spacings (GtkTable «table, guint spacing) 


Sets the space between every column in table equal to spacing. 


e guint gtk_table_get_default_col_spacing (GtkTable «table) 


Gets the default column spacing for the table. 


e void gtk_table_set_homogeneous (GtkTable «table, gboolean homogeneous) 


Changes the homogenous property of table cells, ie. 


e gboolean gtk_table_get_homogeneous (GtkTable «table) 


Returns whether the table cells are all constrained to the same width and height. 
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6.82.2 Function Documentation 


6.82.2.1 void gtk_table_attach (GtkTable x table, GtkWidget x child, guint left_attach, guint 
right_attach, guint top_attach, guint bottom_attach, GtkAttachOptions xoptions, 
GtkAttachOptions yoptions, guint xpadding, guint ypadding) 


Adds a widget to a table. 


The number of ’cells’ that a widget will occupy is specified by left_attach, right_attach, top_attach and 
bottom_attach. These each represent the leftmost, rightmost, uppermost and lowest column and row num- 
bers of the table. (Columns and rows are indexed from zero). 


Parameters: 
table [in] The GtkTable to add a new widget to. 
child [in] The widget to add. 
left_attach [in] the column number to attach the left side of a child widget to. 
right_attach [in] the column number to attach the right side of a child widget to. 
top_attach [in] the row number to attach the top of a child widget to. 
bottom_attach [in] the row number to attach the bottom of a child widget to. 
xoptions [in] Used to specify the properties of the child widget when the table is resized. 
yoptions [in] The same as xoptions, except this field determines behaviour of vertical resizing. 


xpadding [in] An integer value specifying the padding on the left and right of the widget being added 
to the table. 


ypadding [in] The amount of padding above and below the child widget. 


Returns: 


void 


6.82.2.2 void gtk_table_attach_defaults (GtkTable x table, GtkWidget « widget, guint left_attach, 
guint right_attach, guint top_attach, guint bottom_attach) 


As there are many options associated with gtk_table_attach(), this convenience function provides the pro- 
grammer with a means to add children to a table with identical padding and expansion options. 


The values used for the GtkAttachOptions are GTK_EXPAND | GTK_FILL, and the padding is set to 
0. 
Parameters: 

table [in] The table to add a new child widget to. 

widget [in] The child widget to add. 

left_attach [in] The column number to attach the left side of the child widget to. 

right_attach [in] The column number to attach the right side of the child widget to. 

top_attach [in] The row number to attach the top of the child widget to. 

bottom_attach [in] The row number to attach the bottom of the child widget to. 


Returns: 


void 
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6.82.2.3 guint gtk_table_get_col_spacing (GtkTable « table, guint column) 
Gets the amount of space between column col, and column col + 1. 
See gtk_table_set_col_spacing(). 


Parameters: 


table [in] a GtkTable 


column [in] a column in the table, 0 indicates the first column 


Returns: 


the column spacing 


6.82.2.4 guint gtk_table_get_default_col_spacing (GtkTable x table) 


Gets the default column spacing for the table. 


This is the spacing that will be used for newly added columns. (See gtk_table_set_col_spacings()) 


Parameters: 


table [in] a GtkTable. 


Returns: 


value [in] the default column spacing 


6.82.2.5 guint gtk_table_get_default_row_spacing (GtkTable « table) 


Gets the default row spacing for the table. 


This is the spacing that will be used for newly added rows. (See gtk_table_set_row_spacings()) 


Parameters: 


table [in] a GtkTable. 


Returns: 


value [in] the default row spacing 


6.82.2.6 gboolean gtk_table_get_homogeneous (GtkTable x table) 
Returns whether the table cells are all constrained to the same width and height. 
(See gtk_table_set_homogenous()) 


Parameters: 


table [in] a GtkTable. 


Returns: 


TRUE if the cells are all constrained to the same size 
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6.82.2.7 guint gtk_table_get_row_spacing (GtkTable x table, guint row) 


Gets the amount of space between row row, and row row + 1. 


See gtk_table_set_row_spacing(). 


Parameters: 


table [in] a GtkTable 


row [in] a row in the table, 0 indicates the first row 


Returns: 


the row spacing 


6.82.2.8 GtkWidget gtk_table_new (guint rows, guint columns, gboolean homogeneous) 


Used to create a new table widget. 
An initial size must be given by specifying how many rows and columns the table should have, although this 
can be changed later with gtk_table_resize(). rows and columns must both be in the range 0 .. 65535. 
Parameters: 

rows [in] The number of rows the new table should have. 

columns [in] The number of columns the new table should have. 


homogeneous [in] If set to TRUE, all table cells are resized to the size of the cell containing the largest 
widget. 


Returns: 


A pointer to the the newly created table widget. 


6.82.2.9 void gtk_table_resize (GtkTable x table, guint rows, guint columns) 
If you need to change a table’s size after it has been created, this function allows you to do so. 


Parameters: 
table [in] The GtkTable you wish to change the size of. 
columns [in] The new number of rows. 


homogeneous [in] The new number of columns. 


Returns: 


void 


6.82.2.10 void gtk_table_set_col_spacing (GtkTable x table, guint column, guint spacing) 


Alters the amount of space between a given table column and the following column. 
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Parameters: 


table [in] The GtkTable you wish to change the size of. 
column [in] the column whose spacing should be changed. 


spacing [in] number of pixels that the spacing should take up. 


Returns: 


void 


6.82.2.11 void gtk_table_set_col_spacings (GtkTable x table, guint spacing) 
Sets the space between every column in table equal to spacing. 


Parameters: 


table [in] a GtkTable. 


spacing [in] the number of pixels of space to place between every column in the table. 


Returns: 


void 


6.82.2.12 void gtk_table_set_homogeneous (GtkTable « table, gboolean homogeneous) 


Changes the homogenous property of table cells, ie. 


whether all cells are an equal size or not. 


Parameters: 


table [in] The GtkTable you wish to set the homogeneous properties of. 


homogeneous [in] Set to TRUE to ensure all table cells are the same size. Set to FALSE if this is not 
your desired behaviour. 


Returns: 


void 


6.82.2.13 void gtk_table_set_row_spacing (GtkTable x table, guint row, guint spacing) 
Changes the space between a given table row and the subsequent row. 


Parameters: 


table [in] a GtkTable containing the row whose properties you wish to change. 
columns [in] row number whose spacing will be changed. 


homogeneous [in] number of pixels that the spacing should take up. 


Returns: 


void 
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6.82.2.14 void gtk_table_set_row_spacings (GtkTable + table, guint spacing) 
Sets the space between every row in table equal to spacing. 


Parameters: 


table [in] a GtkTable. 


spacing [in] the number of pixels of space to place between every row in the table. 


Returns: 


void 
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6.83 Scrolling 


Modules 


¢ GtkHScrollBar 


The GtkHScrollbar widget is a widget arranged horizontally creating a scrollbar. 


¢ GtkVScrollBar 


The GtkVScrollbar widget is a widget arranged vertically creating a scrollbar. 


¢ GtkScrolled Window 


it's a container the accepts a single child widget, adds scrollbars to the child widget and optionally draws 
a beveled frame around the child widget. 
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6.84 GtkHScrollBar 


6.84.1 Detailed Description 


The GtkHScrollbar widget is a widget arranged horizontally creating a scrollbar. 


See GtkScrollbar for details on scrollbars. GtkAdjustment pointers may be added to handle the adjustment 
of the scrollbar or it may be left NULL in which case one will be created for you. See GtkAdjustment for 


details. 


Code Example 


GtkWidget *hscrollbar; 
GtkObject *adjl; 
GtkWidget xbox; 


box = gtk_vbox_new (FALSE, 10); 
gtk_container_add (GTK_CONTAINER (window), box); 
gtk_widget_show (box); 


adjl = gtk_adjustment_new (0.0, 0.0, 101.0, 0.1, 1.0, 1.0); 
hscrollbar = gtk_hscrollbar_new (GTK_ADJUSTMENT (adjl)); 


gtk_range_set_update_policy (GTK_RANGE (hscrollbar), 
GTK_UPDATE_CONTINUOUS) ; 


gtk_box_pack_start (GTK_BOX (box), hscrollbar, TRUE, TRUE, 0); 


gtk_widget_show (hscrollbar) ; 


Data Structures 


¢ struct _GtkHScrollbar 


GtkHScrollbar instance structure. 


e struct _GtkHScrollbarClass 


GtkHScrollbar instance class structure. 


Functions 


e GtkWidget x gtk_hscrollbar_new (GtkAdjustment *adjustment) 


Creates a new GtkViewport. 


6.84.2 Function Documentation 


6.84.2.1 GtkWidget» gtk_hscrollbar_new (GtkAdjustment x adjustment) 


Creates a new GtkViewport. 


Parameters: 


adjustment [in] the GtkAdjustment to use, or NULL to create a new adjustment. 
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Returns: 


the new GtkHScrollbar 
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6.85 GtkVScrollBar 


6.85.1 Detailed Description 


The GtkVScrollbar widget is a widget arranged vertically creating a scrollbar. 


See GtkScrollbar for details on scrollbars. GtkAdjustment pointers may be added to handle the adjustment 
of the scrollbar or it may be left NULL in which case one will be created for you. See GtkAdjustment for 
details 


Code Example 


GtkWidget *vscrollbar; 
GtkObject *adjl; 
GtkWidget «box; 


box = gtk_vbox_new (FALSE, 10); 
gtk_container_add (GTK_CONTAINER (window), box); 
gtk_widget_show (box); 


adjl = gtk_adjustment_new (0.0, 0.0, 101.0, 0.1, 1.0, 1.0); 
vscrollbar = gtk_vscrollbar_new (GTK_ADJUSTMENT (adjl)); 


gtk_range_set_update_policy (GTK_RANGE (vscrollbar), 
GTK_UPDATE_CONTINUOUS) ; 


gtk_box_pack_start (GTK_BOX (box), vscrollbar, TRUE, TRUE, 0); 
gtk_widget_show (vscrollbar) ; 


Data Structures 


e struct _GtkV Scrollbar 


GtkVScrollbar instance structure. 


¢ struct _GtkVScrollbarClass 


GtkVScrollbar instance class structure. 


Functions 


e GtkWidget x gtk_vscrollbar_new (GtkAdjustment *adjustment) 


Creates a new vertical scrollbar. 


6.85.2 Function Documentation 
6.85.2.1 GtkWidget* gtk_vscrollbar_new (GtkAdjustment « adjustment) 
Creates a new vertical scrollbar. 


Parameters: 


adjustment [in] the GtkAdjustment to use, or NULL to create a new adjustment. 
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Returns: 


new GtkVScrollbar 
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6.86 GtkScrolled Window 


6.86.1 Detailed Description 


it’s a container the accepts a single child widget, adds scrollbars to the child widget and optionally draws a 
beveled frame around the child widget. 


GtkScrolledWindow is a GtkBin subclass. The scrolled window can work in two ways. Some widgets 
have native scrolling support; these widgets have "slots" for GtkAdjustment objects. [5] Widgets with 
native scroll support include GtkTree View, GtkTextView, and GtkLayout. 


For widgets that lack native scrolling support, the Gtk Viewport widget acts as an adaptor class, implement- 
ing scrollability for child widgets that lack their own scrolling capabilities. Use Gtk Viewport to scroll child 
widgets such as GtkTable, GtkBox, and so on. 


If a widget has native scrolling abilities, it can be added to the GtkScrolledWindow with gtk_container_- 
add(). If a widget does not, you must first add the widget to a Gtk Viewport, then add the Gtk Viewport to 
the scrolled window. The convenience function gtk _scrolled_window_add_with_viewport() does exactly 
this, so you can ignore the presence of the viewport. 


The position of the scrollbars is controlled by the scroll adjustments. See GtkAdjustment for the fields 
in an adjustment - for GtkScrollbar, used by GtkScrolledWindow, the "value" field represents the position 
of the scrollbar, which must be between the "lower" field and "upper - page_size." The "page_size" field 
represents the size of the visible scrollable area. The "step_increment" and "page_increment" fields are 
used when the user asks to step down (using the small stepper arrows) or page down (using for example 
the PageDown key). 


If a GtkScrolledWindow doesn't behave quite as you would like, or doesn't have exactly the right layout, 
it’s very possible to set up your own scrolling with GtkScrollbar and for example a GtkTable. 


Figure 6.17: GtkScrolled Window 
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Code Example: 


GtkWidget *scrolled_window; 
GtkWidget «table; 


// create a new scrolled window. 


scrolled_window = gtk_scrolled_window_new (NULL, NUL 


//the policy is one of GTK_POLICY AUTOMATIC, 


L); 


or GTK_POLICY_ALWAYS. 
//GTK_POLICY_AUTOMATIC will automatically decide whether you need 
//scrollbars, whereas GTK_POLICY_ALWAYS will always 

//there. The first one is the horizontal scrollbar, 
gtk_container_set_border_width (GTK_CONTAINER (scrol 


gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW 


GTK_POLICY_AUTOMAT 


leave the scrollbars 


the second, the vertical. 


led_window), 10); 


(scrolled_window), 
C, GTK_POLICY_ALWAYS) ; 


// The dialog window is created with a vbox packed into it. 
gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window) ->vbox), scrolled_window, 


TRUE, TRUE, 0); 
gtk_widget_show (scrolled_window) ; 


// create a table of 10 by 10 squares. 
table = gtk_table_new (10, 10, FALSE); 


// set the spacing to 10 on x and 10 on y 


gtk_table_set_row_spacings (GTK_TABLE (table), 10); 
gtk_table_set_col_spacings (GTK_TABLE (table), 10);B 


// pack the table into the scrolled window 


gtk_scrolled_window_add_with_viewport (GTK_SCROLLED_WINDOW (scrolled_window), table); 


gtk_widget_show (table); 


Data Structures 


e struct _GtkScrolled Window 


scrolled window instance 


e struct _GtkScrolledWindowClass 


scrolled window class 


Functions 


e GtkWidget *  gtk_scrolled_window_new 
*vadjustment) 


Creates a new scrolled window. 


(GtkAdjustment  *hadjustment, GtkAdjustment 


e void gtk_scrolled_window_set_hadjustment (GtkScrolledWindow x*scrolled_window, GtkAdjust- 


ment xhadjustment) 


Sets the GtkAdjustment for the horizontal scrollbar. 


e void gtk_scrolled_window_set_vadjustment (GtkScrolledWindow »xscrolled_window, GtkAdjust- 


ment *vadjustment) 


Sets the GtkAdjustment for the vertical scrollbar. 
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e GtkAdjustment xx  gtk_scrolled_window_get_hadjustment (GtkScrolledWindow  xscrolled_- 
window) 


Returns the horizontal scrollbar's adjustment, used to connect the horizontal scrollbar to the child widget's 
horizontal scroll functionality. 


e GtkAdjustment xx  gtk_scrolled_window_get_vadjustment (GtkScrolledWindow  xscrolled_- 
window) 


Returns the vertical scrollbar's adjustment, used to connect the vertical scrollbar to the child widget's 
vertical scroll functionality. 


e GtkWidget * gtk_scrolled_window_get_hscrollbar (GtkScrolled Window x*scrolled_window) 


Returns the horizontal scrollbar of scrolled_window. 


e GtkWidget * gtk_scrolled_window_get_vscrollbar (GtkScrolled Window x*scrolled_window) 


Returns the vertical scrollbar of scrolled_window. 


e void gtk_scrolled_window_set_policy (GtkScrolledWindow »xscrolled_window, GtkPolicyType 
hscrollbar_policy, GtkPolicyType vscrollbar_policy) 


Sets the scrollbar policy for the horizontal and vertical scrollbars. 


e void gtk_scrolled_window_get_policy (GtkScrolled Window *scrolled_window, GtkPolicyType 
*hscrollbar_policy, GtkPolicy Type *vscrollbar_policy) 


Retrieves the current policy values for the horizontal and vertical scrollbars. 


e void gtk_scrolled_window_set_placement (GtkScrolledWindow *scrolled_window, GtkCornerType 
window_placement) 


Sets the placement of the contents with respect to the scrollbars for the scrolled window. 


e void gtk_scrolled_window_unset_placement (GtkScrolledWindow *scrolled_window) 


Unsets the placement of the contents with respect to the scrollbars for the scrolled window. 


e GtkCornerType gtk_scrolled_window_get_placement (GtkScrolledWindow *scrolled_window) 


Gets the placement of the contents with respect to the scrollbars for the scrolled window. 


e void gtk_scrolled_window_set_shadow_type (GtkScrolledWindow «scrolled_window, GtkShadow- 
Type type) 


Changes the type of shadow drawn around the contents of scrolled_window. 


e GtkShadowType  gtk_scrolled_window_get_shadow_type (GtkScrolledWindow _ xscrolled_- 
window) 


Gets the shadow type of the scrolled window. 


e void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow *scrolled_window, GtkWidget 
*child) 


Used to add children without native scrolling capabilities. 
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6.86.2 Function Documentation 


6.86.2.1 void gtk_scrolled_window_add_with_viewport (GtkScrolledWindow « scrolled_window, 
GtkWidget « child) 


Used to add children without native scrolling capabilities. 


This is simply a convenience function; it is equivalent to adding the unscrollable child to a viewport, then 
adding the viewport to the scrolled window. If a child has native scrolling, use gtk_container_add() instead 
of this function. 


The viewport scrolls the child by moving its GdkWindow, and takes the size of the child to be the size 
of its toplevel GdkWindow. This will be very wrong for most widgets that support native scrolling; for 
example, if you add a widget such as GtkTreeView with a viewport, the whole widget will scroll, including 
the column headings. Thus, widgets with native scrolling support should not be used with the Gtk Viewport 


proxy. 


A widget supports scrolling natively if the set_scroll_adjustments_signal field in GtkWidgetClass is non- 
zero, i.e. has been filled in with a valid signal identifier. 


Parameters: 


— scrolled_window a GtkScrolled Window 


— child Widget you want to scroll. 


Returns: 


void 


6.86.2.2 GtkAdjustment« gtk_scrolled_window_get_hadjustment (GtkScrolledWindow + 
scrolled_window) 


Returns the horizontal scrollbar’s adjustment, used to connect the horizontal scrollbar to the child widget's 
horizontal scroll functionality. 


Parameters: 


— scrolled_window a GtkScrolledWindow 


Returns: 


The horizontal GtkAdjustment. 


6.86.2.3 GtkWidget» gtk_scrolled_window_get_hscrollbar (GtkScrolled Window * 
scrolled_window) 


Returns the horizontal scrollbar of scrolled_window. 


Parameters: 


— scrolled_window a GtkScrolled Window 


Returns: 


the horizontal scrollbar of the scrolled window, or NULL if it does not have one. 
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6.86.2.4 GtkCornerType gtk_scrolled_window_get_placement (GtkScrolledWindow x 
scrolled_window) 


Gets the placement of the contents with respect to the scrollbars for the scrolled window. 


See gtk_scrolled_window_set_placement(). 


Parameters: 


— scrolled_window a GtkScrolledWindow 


Returns: 


the current placement value. 


6.86.2.5 void gtk_scrolled_window_get_policy (GtkScrolledWindow * scrolled_window, 
GtkPolicyType * hscrollbar_policy, GtkPolicyType « vscrollbar_policy) 


Retrieves the current policy values for the horizontal and vertical scrollbars. 


See gtk_scrolled_window_set_policy(). 


Parameters: 
— scrolled_window a GtkScrolled Window 
> hscrollbar_policy location to store the policy for the horizontal scrollbar, or NULL. 


> vscrollbar_policy location to store the policy for the horizontal scrollbar, or NULL. 


Returns: 


void 


6.86.2.6 GtkShadowType gtk_scrolled_window_get_shadow_type (GtkScrolled Window = 
scrolled_window) 


Gets the shadow type of the scrolled window. 


See gtk_scrolled_window_set_shadow_type(). 


Parameters: 


— scrolled_window the current shadow type 


Returns: 


void 


6.86.2.7 GtkAdjustment« gtk_scrolled_window_get_vadjustment (GtkScrolledWindow * 
scrolled_window) 


Returns the vertical scrollbar’s adjustment, used to connect the vertical scrollbar to the child widget’s 
vertical scroll functionality. 
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Parameters: 


— scrolled_window a GtkScrolled Window 


Returns: 


The vertical GtkAdjustment. 


6.86.2.8 GtkWidget» gtk_scrolled_window_get_vscrollbar (GtkScrolledWindow + 
scrolled_window) 


Returns the vertical scrollbar of scrolled_window. 


Parameters: 


— scrolled_window a GtkScrolled Window 


Returns: 


the vertical scrollbar of the scrolled window, or NULL if it does not have one. 


6.86.2.9 GtkWidget* gtk_scrolled_window_new (GtkAdjustment x hadjustment, GtkA djustment = 
vadjustment) 


Creates a new scrolled window. 


The two arguments are the scrolled window’s adjustments; these will be shared with the scrollbars and the 
child widget to keep the bars in sync with the child. Usually you want to pass NULL for the adjustments, 
which will cause the scrolled window to create them for you. 


Parameters: 


— hadjustment Horizontal adjustment. 


— vadjustment Vertical adjustment. 


Returns: 


New scrolled window. 


6.86.2.10 void gtk_scrolled_window_set_hadjustment (GtkScrolled Window + scrolled_window, 
GtkAdjustment x hadjustment) 


Sets the GtkAdjustment for the horizontal scrollbar. 


Parameters: 


— scrolled_window A GtkScrolledWindow. 


— hadjustment Vertical scroll adjustment. 


Returns: 


void 
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6.86.2.11 void gtk_scrolled_window_set_placement (GtkScrolled Window « scrolled_window, 
GtkCornerType window_placement) 


Sets the placement of the contents with respect to the scrollbars for the scrolled window. 


See also gtk_scrolled_window_get_placement() and gtk_scrolled_window_unset_placement(). 


Determines the location of the child widget with respect to the scrollbars. The default is GTK_CORNER_- 
TOP_LEFT, meaning the child is in the top left, with the scrollbars underneath and to the right. Other val- 
ues in GtkCornerType are GTK_CORNER_TOP_RIGHT, GTK_CORNER_BOTTOM_LEFT, and GTK_- 
CORNER_BOTTOM_RIGHT. 


Parameters: 


— scrolled_window a GtkScrolledWindow 


— window_placement Position of the child window. 


Returns: 


void 


6.86.2.12 void gtk_scrolled_window_set_policy (GtkScrolledWindow + scrolled_window, 
GtkPolicyType hscrollbar_policy, GtkPolicyType vscrollbar_policy) 


Sets the scrollbar policy for the horizontal and vertical scrollbars. 


The policy determines when the scrollbar should appear; it is a value from the GtkPolicyType enumeration. 
If GTK_POLICY_ALWAYS, the scrollbar is always present; if GTK_POLICY_NEVER, the scrollbar is 
never present; if GTK_POLICY_AUTOMATIC, the scrollbar is present only if needed (that is, if the slider 
part of the bar would be smaller than the trough - the display is larger than the page size). 
Parameters: 

— scrolled_window a GtkScrolledWindow 

— hscrollbar_policy Policy for horizontal bar. 


— vscrollbar_policy Policy for vertical bar. 


Returns: 


void 


6.86.2.13 void gtk_scrolled_window_set_shadow_type (GtkScrolledWindow x scrolled_window, 
GtkShadowType £ype) 


Changes the type of shadow drawn around the contents of scrolled_window. 


Parameters: 


— scrolled_window a GtkScrolledWindow 


— type kind of shadow to draw around scrolled window contents 


Returns: 


void 
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6.86.2.14 void gtk_scrolled_window_set_vadjustment (GtkScrolled Window « scrolled_window, 
GtkAdjustment x vadjustment) 


Sets the GtkAdjustment for the vertical scrollbar. 


Parameters: 
— scrolled_window a GtkScrolledWindow 


— vadjustment Vertical scroll adjustment. 


Returns: 


void 


6.86.2.15 void gtk_scrolled_window_unset_placement (GtkScrolled Window « scrolled_window) 


Unsets the placement of the contents with respect to the scrollbars for the scrolled window. 


If no window placement is set for a scrolled window, it obeys the "gtk-scrolled-window-placement" XSET- 
TING. 


See also gtk_scrolled_window_set_placement() and gtk_scrolled_window_get_placement(). 


Parameters: 


— scrolled_window a GtkScrolled Window 


Returns: 


void 
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6.87 Ornaments 


Modules 


e GtkFrame 


The frame widget is a GtkBin that surrounds its child with a decorative frame and an optional label. 
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6.88 GtkFrame 


6.88.1 Detailed Description 


The frame widget is a GtkBin that surrounds its child with a decorative frame and an optional label. 


If present, the label is drawn in a gap in the top side of the frame. The position of the label can be controlled 
with gtk_frame_set_label_align(). 


Frame 


Figure 6.18: GtkFrame 


Code Example: 


GtkWidget «frame; 

frame = gtk_frame_new (NULL); 

gtk_container_add (GTK_CONTAINER (window), frame) ; 
gtk_frame_set_label (GTK_FRAME (frame), "GTK Frame Widget"); 
gtk_frame_set_label_align (GTK_FRAME (frame), 1.0, 0.0); 
gtk_frame_set_shadow_type (GTK_FRAME (frame), GTK_SHADOW_ETCHED_OUT) ; 
gtk_widget_show (frame) ; 


Data Structures 


e struct _GtkFrame 


GtkFrame instance structure. 


e struct _GtkFrameClass 


GtkFrame instance class structure. 


Functions 


e GtkWidget * gtk_frame_new (const gchar xlabel) 


Creates a new GtkFrame, with optional label label. 
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e void gtk_frame_set_label (GtkFrame «frame, const gchar xlabel) 


Sets the text of the label. 


e G_CONST_RETURN gchar x gtk_frame_get_label (GtkFrame *frame) 
If the frame’s label widget is a GtkLabel, returns the text in the label widget. 


void gtk_frame_set_label_widget (GtkFrame x*frame, GtkWidget «label_widget) 


Sets the label widget for the frame. 


GtkWidget x gtk_frame_get_label_widget (GtkFrame x*frame) 


Retrieves the label widget for the frame. 


void gtk_frame_set_label_align (GtkFrame «frame, gfloat xalign, gfloat yalign) 


Sets the alignment of the frame widget's label. 


void gtk_frame_get_label_align (GtkFrame »frame, gfloat *xalign, gfloat *yalign) 


Retrieves the X and Y alignment of the frame’s label. 


void gtk_frame_set_shadow_type (GtkFrame x*frame, GtkShadowType type) 


Sets the shadow type for frame. 


GtkShadowType gtk _frame_get_shadow_type (GtkFrame *frame) 


Retrieves the shadow type of the frame. 


6.88.2 Function Documentation 
6.88.2.1 G_CONST_RETURN gchar» gtk_frame_get_label (GtkFrame « frame) 


If the frame’s label widget is a GtkLabel, returns the text in the label widget. 


(The frame will have a GtkLabel for the label widget if a non-NULL argument was passed to gtk_frame_- 
new().) 


Parameters: 


— frame : a GtkFrame 


Returns: 


void 


6.88.2.2 void gtk_frame_get_label_align (GtkFrame + frame, gfloat x xalign, gfloat x yalign) 


Retrieves the X and Y alignment of the frame’s label. 


See gtk_frame_set_label_align(). 


Parameters: 


— frame : a GtkFrame 


=> xalign : location to store X alignment of frame’s label, or NULL 
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=> yalign : location to store X alignment of frame’s label, or NULL 


Returns: 


void 


6.88.2.3 GtkWidget* gtk_frame_get_label_widget (GtkFrame + frame) 


Retrieves the label widget for the frame. 


See gtk_frame_set_label_widget(). 


Parameters: 


— frame : a GtkFrame 


Returns: 


the label widget, or NULL if there is none. 


6.88.2.4 GtkShadowType gtk_frame_get_shadow_type (GtkFrame « frame) 


Retrieves the shadow type of the frame. 


See gtk_frame_set_shadow_type(). 


Parameters: 


— frame : a GtkFrame 


Returns: 


the current shadow type of the frame. 


6.88.2.5 GtkWidget gtk_frame_new (const gchar x label) 


Creates a new GtkFrame, with optional label label. 


If label is NULL, the label is omitted. 


Parameters: 


— label : the text to use as the label of the frame 


Returns: 


a new GtkFrame widget 


6.88.2.6 void gtk_frame_set_label (GtkFrame « frame, const gchar x label) 


Sets the text of the label. 


If label is NULL, the current label is removed. 
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Parameters: 


— frame : a GtkFrame 


— label : the text to use as the label of the frame 


Returns: 


void 


6.88.2.7 void gtk_frame_set_label_align (GtkFrame x frame, gfloat xalign, gfloat yalign) 


Sets the alignment of the frame widget's label. 


The default values for a newly created frame are 0.0 and 0.5. 


Parameters: 


— frame : a GtkFrame 


— xalign : The position of the label along the top edge of the widget. A value of 0.0 represents left 
alignment; 1.0 represents right alignment. 


— yalign : The y alignment of the label. A value of 0.0 aligns under the frame; 1.0 aligns above the 
frame. 


Returns: 


void 


6.88.2.8 void gtk_frame_set_label_widget (GtkFrame x frame, GtkWidget « label_widget) 


Sets the label widget for the frame. 


This is the widget that will appear embedded in the top edge of the frame as a title. 


Parameters: 


— frame : a GtkFrame 


— label_widget : the new label widget 


Returns: 


void 


6.88.2.9 void gtk_frame_set_shadow_type (GtkFrame « frame, GtkShadowType type) 


Sets the shadow type for frame. 


Parameters: 


— frame : a GtkFrame 
— type : the new GtkShadowType 


Returns: 


void 
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6.89 Miscellaneous Widgets 


Modules 


e GtkAdjustment 


The GtkAdjustment object represents a value which has an associated lower and upper bound, together with 
step and page increments, and a page size. 


e GtkDrawingArea 


The GtkDrawingArea widget is used for creating custom user interface elements. 


e GtkEventBox 


The GtkEventBox widget is a subclass of GtkBin which also has its own window. 


GtkViewPort 


An adapter which makes widgets scrollable. 
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6.90 GtkAdjustment 


6.90.1 Detailed Description 


The GtkAdjustment object represents a value which has an associated lower and upper bound, together 
with step and page increments, and a page size. 


It is used within several GTK+ widgets, including GtkSpinButton, GtkViewport, and GtkRange (which is 
a base class for GtkHScrollbar, GtkVScrollbar, GtkHScale, and GtkVScale). 


The GtkAdjustment object does not update the value itself. Instead it is left up to the owner of the GtkAd- 
justment to control the value. 


The owner of the GtkAdjustment typically calls the gtk_adjustment_value_changed() and gtk_adjustment_- 
changed() functions after changing the value and its bounds. This results in the emission of the "value_- 
changed" or "changed" signal respectively. 


Numerical Precision 


The values in a GtkAdjustment are stored as double precision floating point values. More about the different 
floating point types can be found in the corresponding IEEE Floating Point Standard. In most GtkAdjust- 
ment applications, the value member contains a computed number, for instance because the adjustment is 
updated by a GtkSpinButton or GtkRange widget which assign adjustment values based on computations 
which use user input with pixel precision. 


When floats/doubles are computed, they almost never represent the exact number wanted or needed, but 
only an approximation of the real value, because floating point numbers are approximations of real numbers 
by design (needed to represent infinite precision numbers in a finite number of memory cells). In the case 
of a range, spin button or similar widget where the current value is represented by a floating point number 
(i.e. an inexact approximation of the real value needed), adjustment->upper and adjustment->lower may 
or may not be represented exactly in adjustment->value, depending on the implementation. That means, 
even if a spinner or range looks like it represents adjustment->lower or adjustment- >upper in the graphical 
display, the actual adjustment->value may very well be off by a small number (epsilon) that corresponds 
to ca. half a pixel at the GUI. To compensate for such boundary cases accurately in user code, additional 
logic may be required, for instance: 


Code Example 


//retrieve a computed floating point value 


double myval = gtk_spin_button_get_value (spinner); 
double myval = gtk_range_get_value (range); 
double myval = gtk_progress_get_value (progress_widget) ; 


double myval = gtk_adjustment_get_value (adjustment) ; 


//adjust for border cases, assuming a screen resolution < 65536 pixels 
const double epsilon = 0.0000152587890625; // 1.0 / 2%16 


if (fabs (myval - adjustment->lower) < epsilon) 
myval = adjustment->lower; 

if (fabs (myval - (adjustment->upper - adjustment->page_size)) < epsilon) 
myval = adjustment->upper - adjustment->page_size; 


While this compensation code makes some more implicit assumptions, like the range (adjustment- >upper 
- adjustment->lower) not being significantly smaller than 1 and only being a few magnitudes larger than 
the amount of pixels on screen, and while all code that deals with floating point numbers always warrants 
a detailed precision analysis, it should work out well in practice for the vast majority of cases in Gtk+ and 
uses of adjustment->value in Gtk+ applications. But as mentioned, there are more issues that need to be 
taken care of when dealing with floating point numbers. 
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Many of those are addressed by books like Numerical Recipes in C, in particular the chapter 1.3 Error, 
Accuracy, and Stability is a highly recommended read. And a further recommended reading is the paper 
What Every Computer Scientist Should Know About Floating-Point Arithmetic. 


Data Structures 


e struct _GtkAdjustment 


GtkAdjustment instance stucture. 


e struct _GtkAdjustmentClass 


GtkAdjustment instance class stucture. 


Functions 


e GtkObject x» gtk_adjustment_new (gdouble value, gdouble lower, gdouble upper, gdouble step_- 
increment, gdouble page_increment, gdouble page_size) 


Creates a new GtkAdjustment. 


e void gtk_adjustment_changed (GtkAdjustment adjustment) 
Emits a "changed" signal from the GtkAdjustment. 


e void gtk_adjustment_value_changed (GtkAdjustment *adjustment) 


Emits a "value_changed" signal from the GtkAdjustment. 


e void gtk_adjustment_clamp_page (GtkAdjustment *adjustment, gdouble lower, gdouble upper) 


Updates the GtkAdjustment value to ensure that the range between lower and upper is in the current page 
(i.e. 


e gdouble gtk_adjustment_get_value (GtkAdjustment *adjustment) 


Gets the current value of the adjustment. 


e void gtk_adjustment_set_value (GtkAdjustment «adjustment, gdouble value) 
Sets the GtkAdjustment value. 


6.90.2 Function Documentation 
6.90.2.1 void gtk_adjustment_changed (GtkAdjustment x adjustment) 


Emits a "changed" signal from the GtkAdjustment. 


This is typically called by the owner of the GtkAdjustment after it has changed any of the GtkAdjustment 
fields other than the value. 


Parameters: 


adjustment [in] a GtkAdjustment 


Returns: 


void 
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6.90.2.2 void gtk_adjustment_clamp_page (GtkA djustment * adjustment, gdouble lower, gdouble 
upper) 


Updates the GtkAdjustment value to ensure that the range between lower and upper is in the current page 
(1.e. 
between value and value + page_size). If the range is larger than the page size, then only the start of it will 
be in the current page. A "changed" signal will be emitted if the value is changed. 
Parameters: 

adjustment [in] a GtkAdjustment 

lower [in] the lower value. 


upper [in] the upper value. 


Returns: 


void 


6.90.2.3 gdouble gtk_adjustment_get_value (GtkAdjustment « adjustment) 


Gets the current value of the adjustment. 


See gtk_adjustment_set_value(). 


Parameters: 


adjustment [in] a GtkAdjustment 


Returns: 


The current value of the adjustment. 


6.90.2.4 GtkObject« gtk_adjustment_new (gdouble value, gdouble lower, gdouble upper, gdouble 
step_increment, gdouble page_increment, gdouble page_size) 


Creates a new GtkAdjustment. 


Parameters: 
value [in] the initial value. 

lower [in] the minimum value. 

upper [in] the maximum value. 

step_increment [in] the step increment. 

page_increment [in] the page increment. 


page_size [in] the page size. 


Returns: 


a new GtkAdjustment. 
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6.90.2.5 void gtk_adjustment_set_value (GtkAdjustment x adjustment, gdouble value) 


Sets the GtkAdjustment value. 

The value is clamped to lie between adjustment->lower and adjustment->upper. 

Note that for adjustments which are used in a GtkScrollbar, the effective range of allowed values goes from 
adjustment->lower to adjustment->upper - adjustment->page_size. 

Parameters: 


adjustment [in] a GtkAdjustment 


value [in] the new value. 


Returns: 


void 


6.90.2.6 void gtk_adjustment_value_changed (GtkAdjustment x adjustment) 


Emits a "value_changed" signal from the Gtk Adjustment. 


This is typically called by the owner of the GtkAdjustment after it has changed the GtkAdjustment value 
field. 


Parameters: 


adjustment [in] a GtkAdjustment 


Returns: 


void 
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6.91 GtkDrawingArea 


6.91.1 Detailed Description 


The GtkDrawingArea widget is used for creating custom user interface elements. 


It’s essentially a blank widget; you can draw on widget->window. After creating a drawing area, the 
application may want to connect to: 


Mouse and button press signals to respond to input from the user. (Use gtk_widget_add_events() to enable 
events you wish to receive.) 


The "realize" signal to take any necessary actions when the widget is instantiated on a particular display. 
(Create GDK resources in response to this signal.) The "configure_event" signal to take any necessary 
actions when the widget changes size. 


The "expose_event" signal to handle redrawing the contents of the widget. Expose events are normally 
delivered when a drawing area first comes onscreen, or when it's covered by another window and then 
uncovered (exposed). You can also force an expose event by adding to the "damage region" of the drawing 
area’s window; gtk_widget_queue_draw_area() and gdk_window_invalidate_rect() are equally good ways 
to do this. You’ll then get an expose event for the invalid region. 


The available routines for drawing are documented on the GDK Drawing Primitives page. See also gdk_- 
pixbuf_render_to_drawable() for drawing a GdkPixbuf. 


To receive mouse events on a drawing area, you will need to enable them with gtk_widget_add_events(). To 
receive keyboard events, you will need to set the GTK_CAN_FOCUS flag on the drawing area, and should 
probably draw some user-visible indication that the drawing area is focused. Use the GTK_HAS_FOCUS() 
macro in your expose event handler to decide whether to draw the focus indicator. See gtk_paint_focus() 
for one way to draw focus. 


The following code portion demonstrates using a drawing area to display a circle in the normal widget 
foreground color. Note that GDK automatically clears the exposed area to the background color before 
sending the expose event, and that drawing is implicitly clipped to the exposed area. 


Code Example 


gboolean 
expose_event_callback (GtkWidget «widget, GdkEventExpose *event, gpointer data) 
{ 
gdk_draw_arc (widget->window, 
widget->style->fg_gc[GTK_WIDGET_STATE (widget)], 
TRUE, 
0, 0, widget->allocation.width, widget->allocation.height, 
0, 64 * 360); 


return TRUE; 
} 
¡(PRE | 
GtkWidget *drawing_area = gtk_drawing_area_new (); 
gtk_widget_set_size_request (drawing_area, 100, 100); 
g_signal_connect (G_OBJECT (drawing_area), "expose_event", 
G_CALLBACK (expose_event_callback), NULL); 


Data Structures 


e struct _GtkDrawingArea 


GtkDrawingArea instance structure. 


e struct _GtkDrawingAreaClass 
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GtkDrawingArea instance class structure. 


Functions 


e GtkWidget * gtk_drawing_area_new (void) 


Creates a new drawing area. 


6.91.2 Function Documentation 
6.91.2.1 GtkWidget gtk_drawing_area_new (void) 
Creates a new drawing area. 


Returns: 


a new GtkDrawingArea 
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6.92 GtkEventBox 


6.92.1 Detailed Description 


The GtkEventBox widget is a subclass of GtkBin which also has its own window. 
It is useful since it allows you to catch events for widgets which do not have their own window. 


Code Example: 


GtkWidget *event_box;; 


event_box = gtk_event_box_new (); 
gtk_container_add (GTK_CONTAINER (window), event_box); 
gtk_widget_show (event_box); 


// Create a long label 
label = gtk_label_new ("Click here to quit, quit, quit, quit, quit"); 
gtk_container_add (GTK_CONTAINER (event_box), label); 


// Clip it short 
gtk_widget_set_size_request (label, 110, 20); 


// And bind an action to it 

gtk_widget_set_events (event_box, GDK_BUTTON_PRESS_MASK) ; 

g_signal_connect (G_OBJECT (event_box), "button_press_event", 
G_CALLBACK (exit), NULL); 


// Yet one more thing you need an X window for 
gtk_widget_realize (event_box) ; 
gdk_window_set_cursor (event_box->window, gdk_cursor_new (GDK_HAND1)); 


Data Structures 


e struct _GtkEventBox 


GtkEventBox instance structure. 


e struct _GtkEventBoxClass 


GtkEventBox instance class structure. 


Functions 


e GtkWidget * gtk_event_box_new (void) 


Creates a new GtkEventBox. 


e gboolean gtk_event_box_get_visible_window (GtkEventBox *event_box) 


Returns whether the event box has a visible window. 


e void gtk_event_box_set_visible_window (GtkEventBox *event_box, gboolean visible_window) 


Set whether the event box uses a visible or invisible child window. 


e gboolean gtk_event_box_get_above_child (GtkEventBox *event_box) 


Returns whether the event box window is above or below the windows of its child. 


e void gtk_event_box_set_above_child (GtkEventBox *event_box, gboolean above_child) 
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Set whether the event box window is positioned above the windows of its child, as opposed to below it. 


6.92.2 Function Documentation 


6.92.2.1 gboolean gtk_event_box_get_above_child (GtkEventBox + event_box) 


Returns whether the event box window is above or below the windows of its child. 


See gtk_event_box_set_above_child() for details. 


Parameters: 


— event_box a GtkEventBox 


Returns: 


TRUE if the event box window is above the window of its child. 


6.92.2.2 gboolean gtk_event_box_get_visible_window (GtkEventBox * event_box) 


Returns whether the event box has a visible window. 


Parameters: 


— event_box a GtkEventBox 


Returns: 


TRUE if the event box window is visible 


6.92.2.3 GtkWidget» gtk_event_box_new (void) 


Creates a new GtkEventBox. 


Returns: 


a new GtkEventBox. 


6.92.2.4 void gtk_event_box_set_above_child (GtkEventBox « event_box, gboolean above_child) 


Set whether the event box window is positioned above the windows of its child, as opposed to below it. 


If the window is above, all events inside the event box will go to the event box. If the window is below, 
events in windows of child widgets will first got to that widget, and then to its parents. 


The default is to keep the window below the child. 
Parameters: 


— event_box a GtkEventBox 
— above_child TRUE if the event box window is above the windows of its child 


Returns: 


void 
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6.92.2.5 void gtk_event_box_set_visible_window (GtkEventBox x event_box, gboolean 
visible_window) 


Set whether the event box uses a visible or invisible child window. 
The default is to use visible windows. 


In an invisible window event box, the window that that the event box creates is a GDK_INPUT_ONLY 
window, which means that it is invisible and only serves to receive events. 


A visible window event box creates a visible (GDK_INPUT_OUTPUT) window that acts as the parent 
window for all the widgets contained in the event box. 


You should generally make your event box invisible if you just want to trap events. Creating a visible 
window may cause artifacts that are visible to the user, especially if the user is using a theme with gradients 
or pixmaps. 


The main reason to create a non input-only event box is if you want to set the background to a different 
color or draw on it. 


Note 


There is one unexpected issue for an invisible event box that has its window below the child. (See gtk_- 
event_box_set_above_child().) Since the input-only window is not an ancestor window of any windows 
that descendent widgets of the event box create, events on these windows aren’t propagated up by the 
windowing system, but only by GTK+. The practical effect of this is if an event isn’t in the event mask for 
the descendant window (see gtk_widget_add_events()), it won’t be received by the event box. 


This problem doesn’t occur for visible event boxes, because in that case, the event box window is actually 
the ancestor of the descendant windows, not just at the same place on the screen. 
Parameters: 


— event_box a GtkEventBox 


— visible_window boolean value 


Returns: 


void 
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6.93 GtkViewPort 


6.93.1 Detailed Description 


An adapter which makes widgets scrollable. 


Data Structures 


e struct _GtkViewport 


GtkViewport instance structure. 


e struct _GtkViewportClass 


GtkViewport instance class structure. 


Functions 


e GtkWidget * gtk_viewport_new (GtkAdjustment *hadjustment, GtkAdjustment *vadjustment) 


Creates a new GtkViewport with the given adjustments. 


e GtkAdjustment * gtk_viewport_get_hadjustment (Gtk Viewport *viewport) 


Returns the horizontal adjustment of the viewport. 


e GtkAdjustment x gtk_viewport_get_vadjustment (Gtk Viewport *viewport) 


Returns the vertical adjustment of the viewport. 


e void gtk_viewport_set_hadjustment (Gtk Viewport *viewport, Gtk Adjustment *adjustment) 


Sets the horizontal adjustment of the viewport. 


e void gtk_viewport_set_vadjustment (GtkViewport «viewport, GtkAdjustment *adjustment) 


Sets the vertical adjustment of the viewport. 


e void gtk_viewport_set_shadow_type (Gtk Viewport «viewport, GtkShadowType type) 


Sets the shadow type of the viewport. 


e GtkShadowType gtk_viewport_get_shadow_type (Gtk Viewport *viewport) 
Gets the shadow type of the GtkViewport. 


6.93.2 Function Documentation 
6.93.2.1 GtkAdjustment* gtk_viewport_get_hadjustment (GtkViewport x viewport) 
Returns the horizontal adjustment of the viewport. 


Parameters: 


— viewport a GtkViewport. 
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Returns: 


the horizontal adjustment of viewport. 


6.93.2.2 GtkShadowType gtk_viewport_get_shadow_type (GtkViewport x viewport) 


Gets the shadow type of the GtkViewport. 


See gtk_viewport_set_shadow_type(). 


Parameters: 


— viewport a GtkViewport 


Returns: 


the shadow type See gtk_viewport_set_shadow_type() 


6.93.2.3 GtkAdjustmentx gtk_viewport_get_vadjustment (GtkViewport * viewport) 
Returns the vertical adjustment of the viewport. 


Parameters: 


— viewport a GtkViewport. 


Returns: 


the vertical adjustment of viewport. 


6.93.2.4 GtkWidget* gtk_viewport_new (GtkAdjustment x hadjustment, GtkAdjustment + 
vadjustment) 


Creates a new GtkViewport with the given adjustments. 


Parameters: 


— hadjustment horizontal adjustment 


— vadjustment vertical adjustment. 


Returns: 


a new GtkViewport. 


6.93.2.5 void gtk_viewport_set_hadjustment (GtkViewport x viewport, GtkAdjustment + 
adjustment) 


Sets the horizontal adjustment of the viewport. 


Parameters: 


< viewport a GtkViewport 
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— adjustment a GtkAdjustment 


Returns: 


void 


6.93.2.6 void gtk_viewport_set_shadow_type (GtkViewport x viewport, GtkShadowType type) 
Sets the shadow type of the viewport. 


Parameters: 
< viewport a GtkViewport 


— type the new shadow type 


Returns: 


void 


6.93.2.7 void gtk_viewport_set_vadjustment (GtkViewport x viewport, GtkAdjustment + 
adjustment) 


Sets the vertical adjustment of the viewport. 


Parameters: 


— viewport a GtkViewport 


— adjustment a GtkAdjustment 


Returns: 


void 
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6.94 Custom LiMo GTK Widgets 


Modules 


GtkColorChooser 
A Widget for selecting a color. 


GtkFocusBin 


This custom widget combines Label and editable widget together and provides combined focus. 


GtkForm 
This Custom GTK Widget consists of Title bar, Softkeybar and GtkBin container. 


GtkFormattedEntry 
This Custom GTK Widget provides GUI to edit Formatted data like Date, Time & IP Address. 


GtkIndicator 


This Custom widget can be used to display list of indicators, can be used for any kind of Annunciator. 


GtkMainWindow 


This Custom widget provides extended GtkWindow functionalities like adding GtkForm, GtkForm Stack 
management, Scrollable Window title etc. 


GtkMessageDialog 
This custom dialog widget provides predefined set of dialogs like INFO, ERROR, WARNING dialogs. 


GtkSimpleList 


This widget provides simple one level List UI functionality. 


GtkSoftkeyBar 
This Custom widget provides Softkey Bar functionality for Mobile GUI applications. 


GtkSpin 
This GTKSpin widget is enhanced for mobile environment with LEFT/RIGHT key Navigation support. 


GtkSymbolDialog 


This Custom dialog widget displays set of symbols/letters in the Grid fashion and provides option to navi- 
gate, provides option to select one value from set of displayed items. 
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6.95 GtkColorChooser 


6.95.1 Detailed Description 


A Widget for selecting a color. 


This widget is inherited from GtkWidget and is a horizontal list which you can select color with. 


Code Example: 


Widget* color_chooser 


GdkColor color; 
color.red = Oxffff; 
color.green = 0; 
color.blue = 0; 
gtk_color_chooser_add 


color.red = 0; 
color.green = Oxffff; 
color.blue = 0; 

gtk_color_chooser_add 


color.red = 0; 
color.green = 0; 
color.blue = Oxffff; 
gtk_color_chooser_add 


gtk_widget_show(color_ 


tlorthooser 


Figure 6.19: GTKColorChooser 


= gtk_color_chooser_new(); 


(GTK_COLOR_CHOOSER (color_chooser), 


(GTK_COLOR_CHOOSER (color_chooser), 


(GTK_COLOR_CHOOSER (color_chooser), 


chooser); 


&color); 


&color); 


&color); 
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Since 


LIMO RI 


Data Structures 


e struct _GtkColorChooser 


GtkColorChooser instance structure. 


e struct _GtkColorChooserClass 


GtkColorChooserClass instance structure. 


Functions 


e GType gtk_color_chooser_get_type (void) G_GNUC_CONST 


This Fuction returns GType. 


e GtkWidget * gtk_color_chooser_new (GtkColorChooserStyle style) 


Create color chooser widget that can select the color value. 


e void gtk_color_chooser_add (GtkColorChooser *colorchooser, GdkColor x*color) 
Add color to GtkColorChooser. 


e void gtk_color_chooser_insert (GtkColorChooser *colorchooser, GdkColor «color, guint index) 


Insert the color of GtkColorChooser to specified index. 


e void gtk_color_chooser_remove (GtkColorChooser *colorchooser, guint index) 


Remove the color of specified index of GtkColorChooser. 


e void gtk_color_chooser_remove_all (GtkColorChooser *colorchooser) 


Remove all color of GtkColorChooser. 


e void gtk_color_chooser_get (GtkColorChooser *colorchooser, GdkColor *outcolor, guint index) 
Get the GdkColor of specified index GtkColorChooser. 


e void gtk_color_chooser_get_selection (GtkColorChooser *colorchooser, GdkColor *outcolor) 


Get currently seleted GdkColor in GtkColorChooser. 


e guint gtk_color_chooser_get_selection_index (GtkColorChooser *colorchooser) 


Return currently selected index to GtkColorChooser. 


e void gtk_color_chooser_set_selection_index (GtkColorChooser *colorchooser, guint index) 


Set Selected index to GtkColorChooser. 


e guint gtk_color_chooser_get_count (GtkColorChooser *colorchooser) 
Return The number of added GdkColor in GtkColorChooser. 


e void gtk_color_chooser_set (GtkColorChooser *colorchooser, GdkColor «color, guint index) 


Set the color of specified index of color chooser with GdkColor. 
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void gtk_color_chooser_convert_color_hue (GtkColorChooser *colorchooser, GdkColor *color) 


Set the color in hue style to GtkColorChooser. 


void gtk_color_chooser_convert_color_saturation (GtkColorChooser *colorchooser, GdkColor 
*color) 


Change the GtkColorChooser Saturation style that relation to GdkColor value. 


void gtk_color_chooser_convert_color_value (GtkColorChooser *colorchooser, GdkColor x*color) 


Change the GtkColorChooser value style that relation to GdkColor value. 


void gtk_color_chooser_extraction_color_hue (GtkColorChooser *colorchooser, GdkColor «color, 
gdouble «hue) 


Extract the hue from the GdkColor. 


void gtk_color_chooser_extraction_color_saturation (GtkColorChooser *colorchooser, GdkColor 
«color, gdouble *saturation) 


Extract the saturation from the GdkColor. 


void gtk_color_chooser_extraction_color_value (GtkColorChooser *colorchooser, GdkColor «color, 
gdouble *value) 


Extract the value from the GdkColor. 


void gtk_color_chooser_mix_color_hsv (GtkColorChooser *colorchooser, GdkColor x*color, gdou- 
ble h, gdouble s, gdouble v) 


Converts a color from HSV space to RGB Input values must be in the [0.0, 1.0] range. 


guint gtk_color_chooser_get_color_index (GtkColorChooser *colorchooser, GdkColor *color) 


Return index of color to GtkColorChooser. 


gchar * gtk_color_chooser_color_to_string (const GdkColor x*color) 


Get the color name with string. 


gboolean gtk_color_chooser_color_from_string (const gchar «str, GdkColor **colors) 


Change string to color. 


6.95.2 Function Documentation 


6.95.2.1 void gtk_color_chooser_add (GtkColorChooser x colorchooser, GdkColor * color) 


Add color to GtkColorChooser. 


Parameters: 


Since 


LIMO R1 


— colorchooser,: specifies the GtkColorChooser 


— color,: specifies the GdkColor 
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6.95.2.2 gboolean gtk_color_chooser_color_from_string (const gchar + str, GdkColor ** colors) 


Change string to color. 


Input string format is "#FF0000" when Gdkcolor RED. 


Parameters: 


— str: a string encoding a color 


— colors,: return location for allocated array of GdkColor 


See also: 


gtk- color chooser color to string) 


Since 


LIMO RI 


6.95.2.3 gchar» gtk_color_chooser_color_to_string (const GdkColor « color) 


Get the color name with string. 


If GdkColor is RED then output is "#FF0000". Outupt format is "#RRGGBB". The string must be freed 
after use. 


Parameters: 


— color,: specifies the GdkColor 


Returns: 


allocated string encoding the color 


Remarks: 


The returned string should be freed when no longer needed 


See also: 


gtk color chooser color from string () 


Since 


LIMO R1 


6.95.2.4 void gtk_color_chooser_convert_color_hue (GtkColorChooser « colorchooser, GdkColor 
x color) 
Set the color in hue style to GtkColorChooser. 


If you create GtkColorChooser with gtk_color_chooser_new(), then don’t need this function. gtk_color_- 
chooser_new() use this function, and set automatically. 


Parameters: 


— colorchooser,: specifies the GtkColorChooser 
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— color,: specifies the GdkColor 


Since 


LIMO R1 


6.95.2.5 void gtk_color_chooser_convert_color_saturation (GtkColorChooser * colorchooser, 
GdkColor x color) 


Change the GtkColorChooser Saturation style that relation to GdkColor value. 


Parameters: 
— colorchooser : specifies the GtkColorChooser 


— color,: specifies the GdkColor 


Since 


LIMO R1 


6.95.2.6 void gtk_color_chooser_convert_color_value (GtkColorChooser x colorchooser, 
GdkColor x color) 


Change the GtkColorChooser value style that relation to GdkColor value. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 


— color,: specifies the GdkColor 


Since 


LIMO R1 


6.95.2.7 void gtk_color_chooser_extraction_color_hue (GtkColorChooser x colorchooser, 
GdkColor « color, gdouble x hue) 


Extract the hue from the GdkColor. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 
— color : specifies the GdkColor 


— hue,: value for the hue component 


Since 


LIMO RI 
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6.95.2.8 void gtk_color_chooser_extraction_color_saturation (GtkColorChooser * colorchooser, 
GdkColor x color, gdouble x saturation) 


Extract the saturation from the GdkColor. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 
— color,: specifies the GdkColor 


— saturation,: value for the saturation component 


Since 


LIMO RI 


6.95.2.9 void gtk_color_chooser_extraction_color_value (GtkColorChooser x colorchooser, 
GdkColor x color, gdouble x value) 


Extract the value from the GdkColor. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 
— color,: specifies the GdkColor 


> value : value for the value component 


Since 


LIMO R1 


6.95.2.10 void gtk_color_chooser_get (GtkColorChooser * colorchooser, GdkColor * outcolor, 
guint index) 
Get the GdkColor of specified index GtkColorChooser. 


If index is under O then index is O , index is bigger than max then index replaced with max index. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 
> outcolor,: specifies the GdkColor 


— index,: specifies the index 


Since 


LIMO R1 
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6.95.2.11 guint gtk_color_chooser_get_color_index (GtkColorChooser * colorchooser, GdkColor + 
color) 


Return index of color to GtkColorChooser. 


Search the color and returns the index. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 


— colorchooser,: specifies the GtkColorChooser 


Returns: 


index of color 


Since 


LIMO R1 


6.95.2.12 guint gtk_color_chooser_get_count (GtkColorChooser * colorchooser) 


Return The number of added GdkColor in GtkColorChooser. 


Parameters: 


— colorchooser,: specifies the GtkColorChooser 


Returns: 


the number of added GdkColor. 


Since 


LIMO RI 


6.95.2.13 void gtk_color_chooser_get_ selection (GtkColorChooser x colorchooser, GdkColor * 
outcolor) 


Get currently seleted GdkColor in GtkColorChooser. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 


— outcolor,: specifies the specifies the GdkColor 


See also: 


gtk_color_chooser_get_selection_index () 


Since 


LIMO RI 
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6.95.2.14 guint gtk_color_chooser_get_selection_index (GtkColorChooser x colorchooser) 


Return currently selected index to GtkColorChooser. 


Parameters: 


— colorchooser,: specifies the GtkColorChooser 


Returns: 


Selection index: 


See also: 


gtk_color_chooser_set_selection_index () 


Since 


LIMO RI 


6.95.2.15 GType gtk_color_chooser_get_type (void) 
This Fuction returns GType. 


Returns: 


GType Type 


Since 


LIMO RI 


6.95.2.16 void gtk_color_chooser_insert (GtkColorChooser x colorchooser, GdkColor x color, 
guint index) 


Insert the color of GtkColorChooser to specified index. 


Parameters: 


— colorchooser,: specifies the GtkColorChooser 
— color,: specifies the GdkColor 


— index,: specifies the index 


Since 


LIMO R1 


6.95.2.17 void gtk_color_chooser_mix_color_hsv (GtkColorChooser x colorchooser, GdkColor x 
color, gdouble h, gdouble s, gdouble v) 


Converts a color from HSV space to RGB Input values must be in the [0.0, 1.0] range. 
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Parameters: 
— colorchooser,: specifies the GtkColorChooser 
— color,: specifies the specifies the GdkColor 
— h,: value for the hue component 
+ §,: value for the saturation component 


— v, value for the value component 


Since 


LIMO R1 


6.95.2.18 GtkWidget« gtk_color_chooser_new (GtkColorChooserStyle style) 


Create color chooser widget that can select the color value. 


Returns: 


color chooser widget. 


Since 


LIMO RI 


6.95.2.19 void gtk_color_chooser_remove (GtkColorChooser « colorchooser, guint index) 


Remove the color of specified index of GtkColorChooser. 


Parameters: 


— colorchooser,: specifies the GtkColorChooser 


— index,: specifies the index 


Since 


LIMO R1 


6.95.2.20 void gtk_color_chooser_remove_all (GtkColorChooser « colorchooser) 


Remove all color of GtkColorChooser. 


Parameters: 


— colorchooser,: specifies the GtkColorChooser 


Since 


LIMO R1 
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6.95.2.21 void gtk_color_chooser_set (GtkColorChooser x colorchooser, GdkColor x color, guint 
index) 


Set the color of specified index of color chooser with GdkColor. 


Parameters: 
— colorchooser,: specifies the GtkColorChooser 
— color,: specifies the GdkColor 


— index,: specifies the index 


Since 


LIMO RI 


6.95.2.22 void gtk_color_chooser_set_selection_index (GtkColorChooser x colorchooser, guint 
index) 


Set Selected index to GtkColorChooser. 


index is corrected automatically when out of range. 


Parameters: 
— colorchooser : specifies the GtkColorChooser 


— index,: specifies the index 


See also: 


gtk_color_chooser_get_selection_index () 


Since 


LIMO RI 
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6.96 GtkFocusBin 


6.96.1 Detailed Description 


This custom widget combines Label and editable widget together and provides combined focus. 


Figure 6.20: GtkFocusBin. 


GtkWidget *focusbin; 
GtkWidget *vbox; 
GtkWidget x*label; 
GtkWidget *formatedentry; 
GtkWidget *mainvbox; 


// Create a focus bin 
focusbin = gtk_focus_bin_new(); 


label = gtk_label_new("Edit IP"); 
gtk_misc_set_alignment (GTK_MISC (label), 0.5, 0.5); 


GTK_WIDGET_UNSET_FLAGS (GTK_WIDGET (label), GTK_CAN_FOCUS); 


formatedentry = gtk_formatted_entry_new (GTK_FORMATTED_ENTRY_IP) ; 
vbox = gtk_vbox_new(FALSE, 2); 

gtk_box_pack_start (GTK_BOX (vbox), label, FALSE, FALSE, 0); 
gtk_box_pack_start (GTK_BOX (vbox), formatedentry, FALSE, FALSE, 0); 
gtk_container_add(GTK_CONTAINER(focusbin), vbox); 


mainvbox = gtk_vbox_new(FALSE, 0); 
gtk_box_pack_start (GTK_BOX (mainvbox) , GIK_WIDGET (focusbin), FALSE, FALSE, 0); 


gtk_focus_bin_set_focusable (GTK_FOCUS_BIN(focusbin), formatedentry) ; 
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gtk_focus_bin_set_title(GTK_FOCUS_BIN(focusbin), GIK_LABEL(label)); 


Since 


LIMO R1 


Data Structures 


e struct _GtkFocusBin 


GtkFocusBin instance structure. 


e struct _GtkFocusBinClass 


GtkFocusBinClass instance structure. 


Functions 


e GType gtk_focus_bin_get_type (void) G_LGNUC_CONST 


This fuction returns GType. 


e GtkWidget * gtk_focus_bin_new (void) 


This Fuction create GtkFocusBin. 


e void gtk_focus_bin_set_focusable (GtkFocusBin *focus_bin, GtkWidget *widget) 


This Fuction registers a widget as its focusable child. 


e GtkWidget * gtk_focus_bin_get_focusable (GtkFocusBin *focus_bin) 


This Fuction returns focusable child widget. 


e void gtk_focus_bin_set_inner_border (GtkFocusBin *focus_bin, const GtkBorder *border) 


Sets focus_bin's inner-border property to border, or clears it if NULL is passed. 


e G_CONST_RETURN GtkBorder x gtk_focus_bin_get_inner_border (GtkFocusBin *focus_bin) 


This function returns the focus_bin's inner-border property. 


e void gtk_focus_bin_set_title (GtkFocusBin *focus_bin, GtkLabel «label) 


This Fuction registers a widget as its title label. 


e GtkLabel x gtk_focus_bin_get_title (GtkFocusBin *focus_bin) 


This Fuction returns title label. 


6.96.2 Function Documentation 
6.96.2.1 GtkWidget* gtk_focus_bin_get_focusable (GtkFocusBin x focus_bin) 
This Fuction returns focusable child widget. 


Parameters: 


— focus_bin specifies the GtkFocusBin 
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Returns: 


focusable child widget 


Since 


LIMO RI 


6.96.2.2 G_CONST_RETURN GtkBorder« gtk_focus_bin_get_inner_border (GtkFocusBin * 
focus_bin) 


This function returns the focus_bin’s inner-border property. 


See gtk_focus_bin_set_inner_border() for more information. 


Parameters: 


— focus_bin GtkFocusBin 


Returns: 


the formatedentry’s GtkBorder, or NULL if none was set. 


Since 


LIMO R1 


6.96.2.3 GtkLabel* gtk_focus_bin_get_title (GtkFocusBin x focus_bin) 
This Fuction returns title label. 


Parameters: 


— focus_bin specifies the GtkFocusBin 


Returns: 


title label widget. 


Since 


LIMO R1 


6.96.2.4 GType gtk_focus_bin_get_type (void) 
This fuction returns GType. 


Returns: 


GType Type 


Since 


LIMO RI 
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6.96.2.5  GtkWidget* gtk_focus_bin_new (void) 
This Fuction create GtkFocusBin. 


Returns: 


This Fuction returns widget. 


Since 


LIMO R1 


6.96.2.6 void gtk_focus_bin_set_focusable (GtkFocusBin x focus_bin, GtkWidget x* widget) 


This Fuction registers a widget as its focusable child. 


Parameters: 
— focus_bin specifies the GtkFocusBin 


— widget focusable child widget 


Remarks: 


If only one can be registered, old widget is renewed by new widget. 


Since 


LIMO RI 


6.96.2.7 void gtk_focus_bin_set_inner_border (GtkFocusBin x focus_bin, const GtkBorder + 
border) 


Sets focus_bin’s inner-border property to border, or clears it if NULL is passed. 
The inner-border is the area around the focus_bin’s child. 
If set, this property overrides the inner-border style property. Overriding the style-provided border is useful 
when you want to do. 
Parameters: 
— focus_bin GtkFocusBin 
— border a GtkBorder, or NULL 


Since 


LIMO R1 


6.96.2.8 void gtk_focus_bin_set_title (GtkFocusBin « focus_bin, GtkLabel x label) 


This Fuction registers a widget as its title label. 
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Parameters: 
— focus_bin specifies the GtkFocusBin 
— label title label widget 


Remarks: 


If only one can be registered, old widget is renewed by new label title. 


Since 


LIMO R1 
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6.97 GtkForm 


6.97.1 Detailed Description 


This Custom GTK Widget consists of Title bar, Softkeybar and GtkBin container. 


GtkWidget 
GtkWidget 
GtkWidget 
GtkWidget 


*form; 
*VDOX; 
xmenu; 
*main_window; 


// creating main window with form 
main_window = gtk_main_window_new (GTK_WIN_STYLE_TITLE) ; 


gtk_widget_set_size_request (main_window, 240, 320); 


gtk_main_window_set_default_title (GTK_MAIN_WINDOW (main_window) ,"<Entry test page>"); 


form = gtk_form_new (TRUE) ; 


gtk_widget_set_size_request (GTK_WIDGET (form), 240, 240); 


gtk_form_set_title(GTK_FORM(main_form), "Gtk-Form Example"); 


gtk_main_window_add_form(GTK_MAIN_WINDOW (main_window),GTK_FORM(form)); 
gtk_main_window_set_current_form(GTK_MAIN_WINDOW (main_window) , GTK_FORM (form) ); 


vbox = gtk_vbox_new (FALSE, 0); 
gtk_container_add (GTK_CONTAINER (form), vbox); 
gtk_widget_show_all (main_window) ; 


menu = gtk_menu_new(); 
gtk_widget_set_name (menu, "Menu") ; 


gtk_form_add_softkey (GTK_FORM (form) , LEFT_SOFTKEY, "Options", 


Since 


NULL, (SoftkeyActionType) SOFTKEY_MENU, GTK_MENU (menu) , NULL) ; 


LIMO R1 


Data Structures 


e struct _GtkForm 


GtkForm represents a scene of GUI application. 


e struct _GtkFormClass 
GtkForm Class. 


Functions 


e GType gtk_form_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


e GtkWidget * gtk_form_new (gboolean has_softkey) 


Constructor of GtkForm. 


e void gtk_form_set_title (GtkForm x*form, gchar xtitle) 
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Set the title of GtkForm. 


void gtk_form_set_icon (GtkForm *form, GtkWidget «image) 
Set the icon of GtkForm. 


gchar * gtk_form_get_title (GtkForm *form) 
Get the title of GtkForm. 


GtkWidget * gtk_form_get_icon (GtkForm x*form) 
Get the icon of GtkForm. 


GtkSoftkeyBar * gtk_form_get_softkey_bar (GtkForm x*form) 
Get the GtkSoftkeyBar widget which GtkForm has. 


gint gtk _form_add_softkey (GtkForm «form, GtkSoftkeyPosition position, gchar *softkey_name, 
GtkWidget *softkey_icon, GtkSoftkeyActionType softkey_action_type, gpointer action, gpointer 
user_data) 


Add softkey to form. 


void gtk_form_set_has_softkey (GtkForm *form, gboolean has_softkey) 


Set GtkForm’s has_softkey member variable. 


gboolean gtk_form_get_has_softkey (GtkForm *form) 


Get GtkForm’s has_softkey member variable’s value. 


void gtk_form_construct (GtkForm «form, gboolean has_softkey) 
Creates GtkForm. 


6.97.2 Function Documentation 


6.97.2.1 gint gtk_form_add_softkey (GtkForm « form, GtkSoftkeyPosition position, gchar x 
softkey_name, GtkWidget « softkey_icon, GtkSoftkeyActionType softkey_action_type, 
gpointer action, gpointer user_data) 


Add softkey to form. 


Parameters: 
— form GtkForm 
— position position of soft key bar. 
— softkey_name softkey name. 
— softkey_icon softkey icon. 
— softkey_action_type softkey action type. 
— action action 


< user_data user_data. 


Returns: 


softkey position 
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Since 


LIMO R1 


6.97.2.2 void gtk_form_construct (GtkForm x form, gboolean has_softkey) 


Creates GtkForm. 


NOTE: This is exposed for UI Builder. Application developers donot call directly. 


Parameters: 
— form GtkForm 


— has_softkey Flag to indicate whether GTKForm should be created with Softkey bar or not. 


Since 


LIMO RI 


6.97.2.3 gboolean gtk_form_get_has_softkey (GtkForm + form) 


Get GtkForm’s has_softkey member variable”s value. 


Parameters: 


— form GtkForm 


Returns: 


has_softkey member variables valuse 


Since 


LIMO RI 


6.97.2.4 GtkWidgetx gtk_form_get_icon (GtkForm x form) 
Get the icon of GtkForm. 


Parameters: 


— form GtkForm 


Returns: 


GtkWidget» GtkWidget 


Since 


LIMO RI 
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6.97.2.5  GtkSoftkeyBar+x gtk_form_get_softkey_bar (GtkForm + form) 


Get the GtkSoftkeyBar widget which GtkForm has. 
If GtkForm has no GtkSoftkeyBar, it returns NULL. 


Parameters: 


— form GtkForm 


Returns: 


GtkSoftkeyBar widget 


Since 


LIMO R1 


6.97.2.6 gchar gtk_form_get_title (GtkForm * form) 
Get the title of GtkForm. 


Parameters: 


— form GtkForm 


Returns: 


title name 


Since 


LIMO R1 


6.97.2.7 GType gtk_form_get_type (void) 
This Fuction returns GType. 


Returns: 


GType Type 


Since 


LIMO R1 


6.97.2.8 GtkWidget« gtk_form_new (gboolean has_softkey) 
Constructor of GtkForm. 


Parameters: 


— has_softkey Only If has_softkey is TRUE, GtkForm has a softkey bar. 
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Returns: 


a new widget 


Since 


LIMO RI 


6.97.2.9 void gtk_form_set_has_softkey (GtkForm x form, gboolean has_softkey) 


Set GtkForm’s has_softkey member variable. 


If has_softkey parameter is TRUE, softkey is created and softkey area of GtkForm is allocated. In this 
case, you have to call gtk_form_add_softkey to set softkey. If has_softkey parameter is FALSE, softkey 
and softkey area are destroyed. 


Parameters: 


— form GtkForm 


— has_softkey whether we have softkey or not 


Since 


LIMO RI 


6.97.2.10 void gtk_form_set_icon (GtkForm + form, GtkWidget x image) 
Set the icon of GtkForm. 


Parameters: 


— form GtkForm 


— image GtkWidget 


Since 


LIMO RI 


6.97.2.11 void gtk_form_set_title (GtkForm * form, gchar * title) 
Set the title of GtkForm. 


Parameters: 


— form GtkForm 
— title title of GtkForm. 


Since 


LIMO RI 
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6.98 GtkFormattedEntry 


6.98.1 Detailed Description 


This Custom GTK Widget provides GUI to edit Formatted data like Date, Time & IP Address. 


‘ Edit time 
255.205 . 255 . 255 


Figure 6.21: GtkFormattedEntry 


Since 


LIMO R1 


Data Structures 


e struct _GtkFormattedEntry 


GtkFormattedEntry instance structure. 


e struct _GtkFormattedEntryClass 


GtkFormattedEntry instance class structure. 


Enumerations 


e enum GtkFormattedEntryStyle { 


GTK_FORMATTED_ENTRY_ERROR, GTK_FORMATTED_ENTRY_DATE_MDY, GTK_- 
FORMATTED_ENTRY_DATE_YDM, GTK_FORMATTED_ENTRY_DATE_YMD, 
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GTK_FORMATTED_ENTRY_12, GTK_FORMATTED_ENTRY_24, GTK_FORMATTED_- 
ENTRY_IP } 


Functions 


GType gtk_formatted_entry_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


GtkWidget x gtk_formatted_entry_new (GtkFormattedEntryStyle style) 
Create GtkFormattedEntry as the style. 


void gtk_formatted_entry_set_style (GtkFormattedEntry *formatted_entry, GtkFormattedEntryStyle 
style) 


Creates GtkFormattedEntry. 


void gtk_formatted_entry_set_inner_border (GtkFormattedEntry *formatted_entry, const GtkBorder 
*«border) 


Sets formatted_entry’s inner-border property to border, or clears it if NULL is passed. 


G_CONST_RETURN GtkBorder x gtk formatted_entry_get_inner_border (GtkFormattedEntry 
*formatted_entry) 


This function returns the formatted_entry’s inner-border property. 


gboolean gtk_formatted_entry_set_tm (GtkFormattedEntry *formatted_entry, struct tm +time) 
Set up the time of GtkFormattedEntry. 


gboolean gtk_formatted_entry_get_tm (GtkFormattedEntry *formatted_entry, struct tm *time) 


Get the value of set up time. 


gboolean gtk_formatted_entry_set_time (GtkFormattedEntry *formatted_entry, time_t «time) 
Set up the time of GtkFormattedEntry. 


gboolean gtk_formatted_entry_get_time (GtkFormattedEntry *formatted_entry, time_t *time) 


Get the value of set up time. 


gboolean gtk_formatted_entry_set_ip (GtkFormattedEntry *formatted_entry, struct in_addr *ip_- 
address) 


Set up the ip of GtkFormattedEntry. 


gboolean gtk_formatted_entry_get_ip (GtkFormattedEntry *formatted_entry, struct in_addr x*ip_- 
address) 


Get the ip which is set up at GtkFormattedEntry. 


gboolean gtk_formatted_entry_set_ip_with_text (GtkFormattedEntry *formatted_entry, gchar *ip_- 
address_text) 


Set up the ip of GtkFormattedEntry. 


GtkFormattedEntryStyle gtk_formatted_entry_get_style (GtkFormattedEntry *formatted_entry) 
Get the style of GtkFormattedEntry. 
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e void gtk_formatted_entry_set_alignment (GtkFormattedEntry *formatted_entry, gfloat xalign) 


Sets the alignment for the contents of the GtkFormattedEntry. 


e gfloat gtk_formatted_entry_get_alignment (GtkFormattedEntry *formatted_entry) 


Gets the value set by gtk_formatted_entry_set_alignment(). 


6.98.2 Enumeration Type Documentation 


6.98.2.1 enum GtkFormattedEntryStyle 


Enumerator: 
GTK_FORMATTED_ENTRY_ERROR Formatted Error. 
GTK_FORMATTED_ENTRY_DATE_MDY Month-Day- Year mode. 
GTK_FORMATTED_ENTRY_DATE_YDM Year-Day-Month mode. 
GTK_FORMATTED_ENTRY_DATE_YMD Year-Month-Day mode. 
GTK_FORMATTED_ENTRY_12 12 hour mode 1-12 
GTK_FORMATTED_ENTRY_24 24 hour mode. 

0-23 

GTK_FORMATTED_ENTRY_IP TP type, 000.000.000.000. 


6.98.3 Function Documentation 
6.98.3.1 gfloat gtk_formatted_entry_get_alignment (GtkFormattedEntry « formatted_entry) 
Gets the value set by gtk_formatted_entry_set_alignment(). 


Parameters: 


— formatted_entry GtkFormattedEntry 


Returns: 


the alignment. 


Since 


LIMO R1 


6.98.3.2 G_CONST_RETURN GtkBorder+x gtk_formatted_entry_get_inner_border 
(GtkFormattedEntry x formatted_entry) 


This function returns the formatted_entry’s inner-border property. 


See gtk_formatted_entry_set_inner_border() for more information. 


Parameters: 


— formatted_entry GtkFormattedEntry 
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Returns: 


the edittime’s GtkBorder, or NULL if none was set. 


Since 


LIMO R1 


6.98.3.3 gboolean gtk_formatted_entry_get_ip (GtkFormattedEntry « formatted_entry, struct 
in_addr « ip_address) 


Get the ip which is set up at GtkFormattedEntry. 


Parameters: 
— formatted_entry GtkFormattedEntry 


> ip_address ip address 


Returns: 


If it fails because the style doesn’t support, this returns FALSE. If it succeeds, this returns TRUE. 


Remarks: 


Style works only in FORMATTED_ENTRY_ IP. 


See also: 


gtk_formatted_entry_set_ip 


Since 


LIMO R1 


6.98.3.4 GtkFormattedEntryStyle gtk_formatted_entry_get_style (GtkFormattedEntry + 
formatted_entry) 


Get the style of GtkFormattedEntry. 


Parameters: 


— formatted_entry GtkFormattedEntry 


Returns: 


The style of GtkFormattedEntry. 


Since 


LIMO RI 
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6.98.3.5  gboolean gtk_formatted_entry_get_time (GtkFormattedEntry x formatted_entry, time_t x 
time) 


Get the value of set up time. 


Parameters: 
— formatted_entry GtkFormattedEntry 
— time The value of set up time. If style is FORMATTED_ENTRY_IP, set the value *0”. 


Returns: 


If it fails because the style doesn’t support, this returns FALSE. If it succeeds, this returns TRUE. 


See also: 


gtk_formatted_entry_set_time 


Remarks: 


If using date in case the style is FORMATTED_ENTRY or using time in case the style is EDIT_DATE, 
this works incorrectly. 


Since 


LIMO R1 


6.98.3.6 gboolean gtk_formatted_entry_get_tm (GtkFormattedEntry « formatted_entry, struct tm 
x time) 


Get the value of set up time. 


Parameters: 


— formatted_entry GtkFormattedEntry 
— time The value of set up time. If style is FORMATTED_ENTRY_IP, set the value NULL. 


Returns: 


If it fails because the style doesn’t support, this returns FALSE. If it succeeds, this returns TRUE. 


See also: 


gtk_formatted_entry_set_tm 


Remarks: 


If using date in case the style is FORMATTED_ENTRY or using time in case the style is EDIT_DATE, 
this works incorrectly. 


Since 


LIMO RI 
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6.98.3.7 GType gtk_formatted_entry_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


Since 


LIMO R1 


6.98.3.8 GtkWidget» gtk_formatted_entry_new (GtkFormattedEntryStyle style) 


Create GtkFormattedEntry as the style. 


Parameters: 


— style style of GtkFormattedEntry 


Returns: 


Widget created as the style. 


Since 


LIMO R1 


6.98.3.9 void gtk_formatted_entry_set_alignment (GtkFormattedEntry x formatted_entry, gfloat 
xalign) 
Sets the alignment for the contents of the GtkFormattedEntry. 
This controls the horizontal positioning of the contents when the displayed text is shorter than the width of 
the GtkFormattedEntry. 
Parameters: 
— formatted_entry GtkFormattedEntry 


— xalign The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts 


Returns: 


The style of GtkFormattedEntry. 


Since 


LIMO R1 
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6.98.3.10 void gtk_formatted_entry_set_inner_border (GtkFormattedEntry x formatted_entry, 
const GtkBorder x border) 


Sets formatted_entry’s inner-border property to border, or clears it if NULL is passed. 
The inner-border is the area around the formatted_entry’s text, but inside its frame. 


Tf set, this property overrides the inner-border style property. 


Parameters: 


— formatted_entry GtkFormattedEntry 
< border a GtkBorder, or NULL 


Since 


LIMO RI 


6.98.3.11 gboolean gtk_formatted_entry_set_ip (GtkFormattedEntry x formatted_entry, struct 
in_addr « ip_address) 

Set up the ip of GtkFormattedEntry. 

If not, the value is set as default value(255.255.255.255). 


Parameters: 
— formatted_entry GtkFormattedEntry 


— ip_address ip address 


Returns: 


If it fails because the style doesn’t support, this returns FALSE. If it succeeds, this returns TRUE. 


Remarks: 


Style works only in FORMATTED_ENTRY_ IP. 


See also: 


gtk_formatted_entry_get_ip 


Since 


LIMO R1 


6.98.3.12 gboolean gtk_formatted_entry_set_ip_with_text (GtkFormattedEntry « formatted_entry, 
gchar x ip_address_text) 


Set up the ip of GtkFormattedEntry. 
If not, the value is set as default value(255.255.255.255). 


Parameters: 


— formatted_entry GtkFormattedEntry 
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— ip_address_text ip address text (ex : "127.0.0.1") 


Returns: 


If it fails because the style doesn’t support, this returns FALSE. If it succeeds, this returns TRUE. 


Remarks: 


Style works only in FORMATTED_ENTRY_IP. 


See also: 


gtk_formatted_entry_set_ip 


Since 


LIMO R1 


6.98.3.13 void gtk_formatted_entry_set_style (GtkFormattedEntry x formatted_entry, 
GtkFormattedEntryStyle style) 

Creates GtkFormattedEntry. 

NOTE: For UiBuilder, do not call function directly 


Parameters: 


— formatted_entry A GtkFormattedEntry 
— style Formatted enty style 


Returns: 
void 


Since 


LIMO R1 


6.98.3.14 gboolean gtk_formatted_entry_set_time (GtkFormattedEntry « formatted_entry, time_t 
x time) 

Set up the time of GtkFormattedEntry. 

If not, the value is set as default value(12:00 AM 01/01/1900). 


Parameters: 


— formatted_entry GtkFormattedEntry 


— time Specifies the time 


Returns: 


If it fails because the style doesn’t support, this returns FALSE. If it succeeds, this returns TRUE. 


See also: 


gtk_formatted_entry_get_time 
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Remarks: 


If style is FORMATTED_ENTRY, use time part only. If style is FORMATTED_ENTRY_DATE, use 
date part only. If FORMATTED_ENTRY_IP, return false. 


Since 


LIMO R1 


6.98.3.15 gboolean gtk_formatted_entry_set_tm (GtkFormattedEntry x formatted_entry, struct tm 
x time) 

Set up the time of GtkFormattedEntry. 

If not, the value is set as default value(12:00 AM 01/01/1900). 


Parameters: 
— formatted _entry GtkFormattedEntry 


— time Specifies the time 


Returns: 


If it fails because the style doesn’t support, this returns FALSE. If it succeeds, this returns TRUE. 


See also: 


gtk_formatted_entry_get_tm 


Remarks: 


If style is FORMATTED_ENTRY, use time part only. If style is FORMATTED_ENTRY_DATE, use 
date part only. If FORMATTED_ENTRY_IP, return false. 


Since 


LIMO R1 
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6.99 GtkIndicator 


6.99.1 Detailed Description 


This Custom widget can be used to display list of indicators, can be used for any kind of Annunciator. 


This widget is inherited from GtkHBox. In Mobile environment this can be used to display icons like RSSI, 
Battery etc... 


Figure 6.22: GtkIndicator 


GtkWidget *main_window; 


// creating main window with form 
main_window = gtk_main_window_new(GTK_WIN_STYLE_TITLE); 


gtk_widget_set_size_request (main_window, 240,320); 
gtk_main_window_set_default_title(GTK_MAIN_WINDOW(main_window),"<Indicator Test page>"); 


main_window->status_area = gtk_hbox_new(FALSE, 0); 
gtk_widget_set_parent (main_window->status_area, GIK_WIDGET (mw) ); 


main_window->indicator = gtk_indicator_new(GTK_INDICATOR_STYLE_MAIN); 
gtk_box_pack_start (GTK_BOX (main_window->status_area), GTK_WIDGET (main_window->indicator), FALSE, FALSE, ( 


gtk_indicator_display_clock (GTK_INDICATOR (main_window->indicator)); 


gtk_widget_show_all (main_window->status_area); 


Since 


LIMO R1 
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Data Structures 


e struct _GtkIndicator 


GtkIndicator instance structure. 


e struct _GtkIndicatorClass 


GtkIndicator instance class structure. 


Enumerations 


« enum 


This enumeration has indicator type. 


Functions 


e GType gtk_indicator_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


e GtkWidget * gtk_indicator_new (GtkIndicatorStyle style) 


Create indicator widget. 


e void gtk_indicator_construct (GtkIndicator «indicator, GtkIndicatorStyle style) 
Construct the GtkIndicator. 


e void gtk_indicator_put_icon (GtkIndicator «indicator, gint position, const gchar *indi_id) 


Put the icon of GtkIndicator to specified position. 


e void gtk_indicator_show (GtkIndicator «indicator, gint position) 


Show the icon of GtkIndicator to specified position. 


e void gtk_indicator_show_all (GtkIndicator indicator) 


Show all icons. 


e void gtk_indicator_display_clock (GtkIndicator indicator) 


Time does setting and shows. 


e gint gtk_indicator_get_data (GtkIndicator «indicator, gint position) 
Get the data of specified position GtkIndicator. 


e void gtk_indicator_set_data (GtkIndicator *indicator, gint indi_value, gboolean on_off, gint indi_- 
lvl) 


Set the data of GtkIndicator. 


6.99.2 Enumeration Type Documentation 
6.99.2.1 anonymous enum 


This enumeration has indicator type. 
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6.99.3 Function Documentation 
6.99.3.1 void gtk_indicator_construct (GtkIndicator x indicator, GtkIndicatorStyle style) 
Construct the GtkIndicator. 


Parameters: 
— indicator specifies the GtkIndicator 


— style a GtkIndicatorStyle 


Returns: 


void 


Since 


LIMO R1 


6.99.3.2 void gtk_indicator_display_clock (GtkIndicator x indicator) 


Time does setting and shows. 


Parameters: 


— indicator specifies the GtkIndicator 


Returns: 


void 


Since 


LIMO R1 


6.99.3.3 gint gtk_indicator_get_data (GtkIndicator x indicator, gint position) 


Get the data of specified position GtkIndicator. 


Parameters: 
— indicator specifies the GtkIndicator 


< position specifies the position 


Returns: 


void 


Since 


LIMO R1 
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6.99.3.4 GType gtk_indicator_get_type (void) 
This Fuction returns GType. 


Returns: 


GType Type 


6.99.3.5 GtkWidget» gtk_indicator_new (GtkIndicatorStyle style) 
Create indicator widget. 


Parameters: 


— style a GtkIndicatorStyle 


Returns: 


indicator widget. 


Since 


LIMO R1 


6.99.3.6 void gtk_indicator_put_icon (GtkIndicator x indicator, gint position, const gchar x indi_id) 
Put the icon of GtkIndicator to specified position. 


Parameters: 
— indicator specifies the GtkIndicator 
< position specifies the position 


— indi_id specifies the icon id 


Returns: 


void 


Since 


LIMO R1 


6.99.3.7 void gtk_indicator_set_data (GtkIndicator x indicator, gint indi_value, gboolean on_off, 
gint indi_Ivl) 


Set the data of GtkIndicator. 


Parameters: 
— indicator specifies the GtkIndicator 


<+ indi_value enum value 
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— on_off On or Off indicator 
— indi_lvl Battery, RSSI level value 


Returns: 


void 


Since 


LIMO R1 


6.99.3.8 void gtk_indicator_show (GtkIndicator x indicator, gint position) 


Show the icon of GtkIndicator to specified position. 


Parameters: 
— indicator specifies the GtkIndicator 


< position specifies the position 


Returns: 


void 


Since 


LIMO R1 


6.99.3.9 void gtk_indicator_show_all (GtkIndicator x indicator) 
Show all icons. 


Parameters: 


— indicator specifies the GtkIndicator 


Returns: 


void 


Since 


LIMO R1 
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6.100 GtkMainWindow 


6.100.1 Detailed Description 


This Custom widget provides extended GtkWindow functionalities like adding GtkForm, GtkForm Stack 
management, Scrollable Window title etc. 


GtkWidget *main_window; 
GtkWidget «form; 
GtkWidget *vbox; 


// creating main window with form 
main_window = gtk_main_window_new (GTK_WIN_STYLE_TITLE) ; 


gtk_widget_set_size_request (main_window, 240, 320); 


gtk_main_window_set_default_title (GTK_MAIN_WINDOW (main_window) ,"<Mobile Window Test>"); 


form = gtk_form_new (TRUE) ; 


gtk_widget_set_size_request (GTK_WIDGET (form), 240, 240); 


gtk_main_window_add_form(GTK_MAIN_WINDOW (main_window) , GTK_FORM (form) ) ; 
gtk_main_window_set_current_form(GTK_MAIN_WINDOW (main_window) , GTK_FORM (form) ); 


vbox = gtk_vbox_new (FALSE, 0); 
gtk_container_add (GTK_CONTAINER (form), vbox); 
gtk_widget_show_all (main_window) ; 


Since 


LIMO RI 


Data Structures 


e struct _GtkMainWindow 


GtkMainWindow is the toplevel frame window which can contain other widgets. 


e struct _GtkMainWindowClass 
GtkMainWindow Class. 


Enumerations 


e enum GtkWindowStyle { 


GTK_WIN_STYLE_NONE, GTK_WIN_STYLE_INDICATOR, GTK_WIN_STYLE_TITLE, 
GTK_WIN_STYLE_APP_TITLE = GTK_WIN_STYLE_TITLE, 


GTK_WIN_STYLE_TITLE_WITHOUT_ICON } 
Window style. 


Functions 


e GType gtk_main_window_get_type (void) G_GNUC_CONST 
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This Fuction returns GType. 


e GtkWidget * gtk_main_window_new (GtkWindowStyle style) 
Constructor of GtkMoblieWindow. 


e GtkWidget * gtk_main_window_new_with_screen (GtkWindowStyle style, GdkScreen *screen) 


Constructor of GtkMoblie Window for the SpecificS creen. 


e guint gtk_main_window_set_current_form (GtkMainWindow «mw, GtkForm *form) 


Makes a form contain to the GtkMainWindow. 


e GtkForm * gtk_main_window_set_current_form_with_index (GtkMainWindow *mw, guint in- 
dex) 


Set current form with a index. 


e GtkForm * gtk_main_window_get_current_form (GtkMainWindow *mw) 


Get current form with a index. 


e gint gtk_main_window_get_form_number (GtkMainWindow *mw) 


Returns the total number of forms added to the Main Window. 


e guint gtk_main_window_add_form (GtkMainWindow *mw, GtkForm *form) 


Adds a form to form_list. 


e GtkForm * gtk_main_window_remove_current_form (GtkMainWindow *mw) 


Removes a current set form from form_list. 


e guint gtk_main_window_remove_form (GtkMainWindow *mw, GtkForm *form) 


Removes a form from form_list. 


e guint gtk_main_window_remove_all_forms (GtkMainWindow *mw) 


Removes all forms from form_list. 


e void gtk_main_window_set_default_title (GtkMainWindow «mw, gchar *default_title) 


Set the default title. 


e void gtk_main_window_set_default_icon (GtkMainWindow *mw, GtkWidget *default_image) 


Set the default icon. 


e void gtk_main_window_set_title_slide_time_out (GtkMainWindow «mw, guint time_out) 


Set sliding time out of the default main window title text . 


e G_CONST_RETURN gchar x gtk_main_window_get_default_title (GtkMainWindow *mw) 


Returns the default title. 


e GtkWidget * gtk_main_window_get_default_icon (GtkMainWindow xmw) 


Returns the default icon. 


e void gtk_main_window_construct (GtkMainWindow *xmw, GtkWindowStyle style, GdkScreen 
*screen) 
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Realizes the Window by creating internal components and doing layout. 


e void gtk_main_window_change_style (GtkMainWindow *mw, GtkWindowStyle style, GtkWidget 
*title_icon) 


Can change main window style during running. 


e void gtk_main_window_set_indicator (GtkMainWindow «mw, gint indi_value, gboolean on_off, 
gint indi_lvl) 


Set indicator. 


6.100.2 Enumeration Type Documentation 
6.100.2.1 enum GtkWindowStyle 


Window style. 


Enumerator: 
GTK_WIN_STYLE_NONE Nothing is shown in the status area. 
GTK_WIN_STYLE_INDICATOR Informations about phone status are shown in the status area. 


GTK_WIN_STYLE_TITLE In addition to GTK_WIN_STYLE_INDICATOR style, application title 
and application icon are shown. 


GTK_WIN_STYLE_APP TITLE backward compatibility 


GTK_WIN_STYLE_TITLE_WITHOUT_ICON In addition to GTK_WIN_STYLE_INDICATOR 
style, application title is shown. 


6.100.3 Function Documentation 


6.100.3.1 guint gtk_main_window_add_form (GtkMainWindow x mw, GtkForm x form) 


Adds a form to form_list. 


You should call gtk_main_window_set_current_form() to contain a form to the GtkMain Window. 


Parameters: 
< mw GtkMainWindow 


— form GtkForm 


Returns: 


list index.(return O if an error occurs) 


Since 


LIMO RI 
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6.100.3.2 void gtk_main_window_change_style (GtkMainWindow « mw, GtkWindowStyle style, 
GtkWidget x title_icon) 


Can change main window style during running. 


Parameters: 


< mw GtkMainWindow 
— style Main window style 


— title_icon title icon widget for status area 


Since 


LIMO R1 


6.100.3.3 void gtk_main_window_construct (GtkMainWindow x mw, GtkWindowStyle style, 
GdkScreen x screen) 


Realizes the Window by creating internal components and doing layout. 


Parameters: 


— mw GtkMainWindow 
— style GtkWindowStyle 


< screen GdkScreen 


Since 


LIMO R1 


6.100.3.4 GtkForm« gtk_main_window_get_current_form (GtkMainWindow x mw) 


Get current form with a index. 


Parameters: 


<— mw the main window; 


Returns: 


current form 


Since 


LIMO R1 


6.100.3.5 GtkWidget» gtk_main_window_get_default_icon (GtkMainWindow « mw) 


Returns the default icon. 


Parameters: 


<— mw GtkMainWindow 
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Returns: 


default icon 


Since 


LIMO R1 


6.100.3.6 G_CONST_RETURN gchar» gtk_main_window_get_default_title (GtkMain Window = 
mw) 


Returns the default title. 


Parameters: 


< mw GtkMainWindow 


Returns: 


default title 


Since 


LIMO R1 


6.100.3.7 gint gtk_main_window_get_form_number (GtkMainWindow x mw) 


Returns the total number of forms added to the Main Window. 


Parameters: 


<— mw the main window; 


Returns: 


integer for normal return, -1 for error. 


Since 


LIMO RI 


6.100.3.8 GType gtk_main_window_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 
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6.100.3.9 GtkWidget« gtk_main_window_new (GtkWindowStyle style) 


Constructor of GtkMoblieWindow. 


Parameters: 


— style Window Style. 


Returns: 


a new GTK Main Window widget. 


Since 


LIMO R1 


6.100.3.10 GtkWidget» gtk_main_window_new_with_screen (GtkWindowStyle style, GdkScreen x 
screen) 


Constructor of GtkMoblieWindow for the SpecificS creen. 


Parameters: 
— style window Style. 


— screen GdkScreen. Screen to which GtkMainWindow should be displayed. 


Returns: 


a new GTK Main Window widget. 


Since 


LIMO R1 


6.100.3.11 guint gtk_main_window_remove_all_forms (GtkMainWindow « mw) 


Removes all forms from form_list. 


Parameters: 


< mw GtkMainWindow 


Returns: 


the number of removed forms. 


Since 


LIMO R1 
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6.100.3.12  GtkForm* gtk_main_window_remove_current_form (GtkMainWindow x mw) 


Removes a current set form from form_list. 


Parameters: 


<— mw GtkMainWindow 


Returns: 


a removed GtkForm pointer.(return O if an error occurs) 


Since 


LIMO RI 


6.100.3.13 guint gtk_main_window_remove_form (GtkMainWindow « mw, GtkForm x form) 


Removes a form from form_list. 


Parameters: 
< mw GtkMainWindow 


— form GtkForm 


Returns: 


list index.(return O if an error occurs) 


Since 


LIMO RI 


6.100.3.14 guint gtk_main_window_set_current_form (GtkMainWindow « mw, GtkForm x form) 


Makes a form contain to the GtkMainWindow. 


Internally gtk_container_add(GTK_CONTAINER(mainwindow), form) is called. The difference between 
gtk_container_add() and gtk_main_window_set_current_form() is that gtk_main_window_set_current_- 
form() is valid only if there is the form in the form_list. 


Parameters: 
< mw GtkMainWindow. 


— form Gtkform. 


Returns: 


list index.(return O if an error occurs) 


Since 


LIMO R1 
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6.100.3.15 GtkForm~« gtk_main_window_set_current_form_with_index (GtkMainWindow « mw, 
guint index) 


Set current form with a index. 


Parameters: 


<— mw the main window; 


— index index of the form in form_list of , should be a positive integer. 


Returns: 


current form 


Since 


LIMO R1 


6.100.3.16 void gtk_main_window_set_default_icon (GtkMainWindow x mw, GtkWidget + 
default_image) 


Set the default icon. 


Parameters: 


< mw GtkMainWindow 
— default_image GtkWidget 


Since 


LIMO R1 


6.100.3.17 void gtk_main_window_set_default_title (GtkMainWindow « mw, gchar x default_title) 


Set the default title. 


Parameters: 


< mw GtkMainWindow 
— default_title default title 


Since 


LIMO R1 


6.100.3.18 void gtk_main_window_set_indicator (GtkMainWindow x mw, gint indi_value, 
gboolean on_off, gint indi_lvl) 


Set indicator. 


Parameters: 


< mw GtkMainWindow 
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— indi_value enum value 
— on_off On or Off indicator 
— indi_lvl Battery, RSSI level value 


Since 


LIMO RI 


6.100.3.19 void gtk_main_window_set_title_slide_time_out (GtkMain Window + mw, guint 
time_out) 


Set sliding time out of the default main window title text . 


Parameters: 


< mw GtkMainWindow 


— time_out sliding time out value. 


Since 


LIMO RI 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


6.101 GtkMessageDialog 793 


6.101 GtkMessageDialog 


6.101.1 Detailed Description 


This custom dialog widget provides predefined set of dialogs like INFO,ERROR, WARNING dialogs. 


This Custom widget provides predefined set of dialogs like INFO Message dialog, WARNING message 
dialog, QUESTION dialog & CONFIRM dialog with set of softkey input options like OK, CLOSE, CAN- 
CEL, YES_NO,OK_CANCEL etc... 


GtkWidget «window; 
static void message_dialog_clicked (GtkButton x*button, 
gpointer user_data) 


GtkWidget *dialog; 
static gint i = 1; 


dialog = gtk_message_dialog_new (GTK_WINDOW (window), 
GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT, 
GTK_MESSAGE_INFO, 
GTK_BUTTONS_OK, 
"This message box has been popped up the following\n" 
"number of times:"); 
gtk_message_dialog_format_secondary_text (GTK_MESSAGE_DIALOG (dialog), 
wed", i); 


gtk_dialog_run (GTK_DIALOG (dialog) ); 
gtk_widget_destroy (dialog); 
itt; 


int main(int argc, char x*x*argv) 
{ 

GtkWidget «dialog; 

GtkWidget «frame; 

GtkWidget *vbox; 


window = gtk_window_new (GTK_WINDOW_TOPLEVEL) ; 
gtk_window_set_title (GTK_WINDOW (window), "Dialogs"); 


frame = gtk_frame_new ("Dialogs"); 
gtk_container_add (GTK_CONTAINER (window), frame) ; 


vbox = gtk_vbox_new (FALSE, 8); 
gtk_container_set_border_width (GTK_CONTAINER (vbox), 8); 
gtk_container_add (GTK_CONTAINER (frame), vbox); 


button = gtk_button_new_with_mnemonic ("_Message Dialog"); 
g_signal_connect (button, "clicked", 

G_CALLBACK (message_dialog_clicked), NULL); 
gtk_box_pack_start (GTK_BOX (vbox), button, FALSE, FALSE, 0); 
gtk_widget_show_all (window) ; 
return 0; 


} 


Since 


LIMO R1 


Data Structures 


e struct _GtkMessageDialog 


GtkMessageDialog instance structure. 
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e struct _GtkMessageDialogClass 


GtkMessageDialog instance class structure. 


Enumerations 


e enum GtkMessageType { 


GTK_MESSAGE_INFO, GTK_MESSAGE_WARNING, GTK_MESSAGE_ QUESTION, GTK_- 
MESSAGE_ERROR, 


GTK_MESSAGE_CONFIRM, GTK_MESSAGE_OTHER | 
The type of message being displayed in the mesaage dialog. 


e enum GtkSoftkeyMenuActionType { 


GTK_SOFTKEY_NONE, GTK_SOFTKEY_OK, GTK_SOFTKEY_CANCEL , GTK_- 
SOFTKEY_OK_CANCEL, 


GTK_SOFTKEY_RETRY_CANCEL } 


Functions 


e GType gtk_message_dialog_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


GtkWidget x* gtk_message_dialog new (GtkWindow *parent, GtkDialogFlags flags, GtkMes- 
sageType type, GtkSoftkeyMenuActionType buttons, const gchar *message_format,...) G_LGNUC_- 
PRINTF(S 


Creates a new message dialog, which is a simple dialog with an icon indicating the dialog type (error, 
warning, etc) and some text the user may want to see. 


GtkWidget *void gtk_message_dialog_set_destroy_timeout (GtkMessageDialog x*dialog, gint 
time) 


set the time when dialog is disappeared on the screen. 


void gtk_message_dialog_set_image (GtkMessageDialog *dialog, GtkWidget *image) 


set the image to be displayed on the screen. 


6.101.2 Enumeration Type Documentation 
6.101.2.1 enum GtkMessageType 
The type of message being displayed in the mesaage dialog. 


Enumerator: 
GTK_MESSAGE_INFO Informational message. 
GTK_MESSAGE_WARNING Warning message. 
GTK_MESSAGE_QUESTION Question message. 
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GTK_MESSAGE_ERROR Error message. 
GTK_MESSAGE_CONFIRM Confirm message. 
GTK_MESSAGE_OTHER Other message. 


6.101.2.2 enum GtkSoftkeyMenuActionType 


Enumerator: 
GTK_SOFTKEY_NONE no actions. 
you should set the timeout value by gtk_message_dialog_set_destroy_timeout 
GTK_SOFTKEY_OK OK action for center softkey. 
GTK_SOFTKEY_CANCEL CANCEL action for right softkey. 
GTK_SOFTKEY_OK_CANCEL YES action for left softkey, NO action for right softkey. 


GTK_SOFTKEY_RETRY_CANCEL OK action for center softkey, CANCEL action for right soft- 
key. 
RETRY action for left softkey, CANCEL action for right softkey 


6.101.3 Function Documentation 
6.101.3.1 GType gtk_message_dialog_get_type (void) 
This Fuction returns GType. 


Returns: 


GType Type 


Since 


LIMO R1 


6.101.3.2 GtkWidget» gtk_message_dialog_new (GtkWindow « parent, GtkDialogFlags 
flags, GtkMessageType type, GtkSoftkeyMenuActionType buttons, const gchar * 
message_format, ...) 


Creates a new message dialog, which is a simple dialog with an icon indicating the dialog type (error, 
warning, etc) and some text the user may want to see. 


When the user press a softkey a "response" signal is emitted with response IDs from GtkResponseType. 
See GtkDialog for more details. 


Parameters: 
— parent transient parent or NULL for none 
— GtkDialogFlags flag 
— GtkMessageType type of message 
— GtkSoftkeyActionType stype of softkey 
— printf() style format string or NULL 
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— ... arguments for message_format 


Returns: 


a new GtkMessageDialog 


Since 


LIMO RI 


6.101.3.3 GtkWidget« void gtk_message_dialog_set_destroy_timeout (GtkMessageDialog « dialog, 
gint time) 


set the time when dialog is disappeared on the screen. 


the dialog is not destroyed really. 


Parameters: 


— dialog GtkMessageDialog 


< time milli-second 


Since 


LIMO RI 


6.101.3.4 void gtk_message_dialog_set_image (GtkMessageDialog « dialog, GtkWidget * image) 
set the image to be displayed on the screen. 


Parameters: 


— dialog GtkMessageDialog 


— image GtkImage 


Since 


LIMO R1 
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6.102 GtkSimpleList 


6.102.1 Detailed Description 


This widget provides simple one level List UI functionality. 


demo Y 


LIST ITEMI 


ITE 
LIST ITEM 


LIST ITEM4LIST ITEMALIST ... 


Figure 6.23: GtkSimpleList 


GtkWidget x*clist; 

GtkWidget «form; 

GtkWidget *vbox; 

GtkWidget *main_window; 
GtkWidget *scrolled_window; 


guint indx; 
gchar xlist_item[4][2] = { { "", "LIST ITEM1" }, 
> NEST: TEME Ffy 
(0. "EST IIEMS" $, 
{ "", "LIST ITEM4LIST ITEM4LIST ITEM4LIST ITEM4" ) }; 


// creating main window with form 
main_window = gtk_main_window_new(GTK_WIN_STYLE_TITLE); 


gtk_widget_set_size_request (main_window, 240, 320); 


gtk_main_window_set_default_title(GTK_MAIN_WINDOW(main_window),"<Entry test page>"); 


form = gtk_form_new(TRUE); 


gtk_widget_set_size_request (GTK_WIDGET (form), 240, 240); 
gtk_form_set_title(GTK_FORM(main_form), "Gtk-Form Example"); 


gtk_main_window_add_form (GTK_MAIN_WINDOW (main_window) , GTK_FORM (form) ) ; 
gtk_main_window_set_current_form(GTK_MAIN_WINDOW (main_window) , GTK_FORM (form) ); 
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vbox=gtk_vbox_new(FALSE, 5); 
gtk_container_add(GTK_CONTAINER (form), vbox); 
gtk_widget_show (vbox) ; 


scrolled_window = gtk_scrolled_window_new (NULL, NULL); 
gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window) , 
GTK_POLICY_NEVER, GTK_POLICY_AUTOMATIC) ; 
gtk_box_pack_start (GTK_BOX(vbox), scrolled_window, TRUE, TRUE, 0); 
gtk_widget_show (scrolled_window) ; 


clist = gtk_simple_list_new(GTK_SIMPLE_LIST_STYLE_NORMAL, 2); 
gtk_clist_set_selection_mode (GTK_CLIST(clist), GTK_SELECTION_BROWSE) ; 
gtk_clist_set_shadow_type (GTK_CLIST(clist), GTK_SHADOW_NONE) ; 


gtk_container_add(GTK_CONTAINER(scrolled_window), clist); 
gtk_widget_show(clist); 


for ( indx=0 ; indx < 4 ; indx++ ) 
gtk_simple_list_append( GTK_SIMPLE_LIST(clist), list_item[indx]); 


Since 


LIMO R1 


Data Structures 


e struct _GtkSimpleList 


GtkSimpleList instance structure. 


e struct _GtkSimpleListClass 


GtkSimpleList instance structure. 


Functions 


e GType gtk_simple_list_get_type (void) G_GNUC_CONST 


This Fuction returns GType. 


e GtkWidget x gtk_simple_list_new (GtkSimpleListStyle style, gint columns) 


Create a new simple list. 


e void gtk_simple_list_set_style (GtkSimpleList *simple_list, GtkSimpleListStyle style) 
Sets the style. 


GtkSimpleListStyle gtk_simple_list_get_style (GtkSimpleList *simple_list) 


Returns the style of the text. 


e gint gtk_simple_list_prepend (GtkSimpleList *simple_list, gchar *text[ ]) 


Append an element a the starting of the simple list. 


e gint gtk_simple_list_append (GtkSimpleList *simple_list, gchar xtext[ ]) 


Append an element a the end of the simple list. 


e gint gtk_simple_list_insert (GtkSimpleList *simple_list, gint row, gchar *text[ ]) 
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Insert an element at the specified row of the simple list. 


void gtk_simple_list_remove (GtkSimpleList *simple_list, gint row) 


removes row at index row 


void gtk_simple_list_clear (GtkSimpleList xclist) 


Clear the entire simple list. 


gboolean gtk_simple_list_is_item_selected (GtkSimpleList *simple_list, gint row) 


Create a new simple list. 


void gtk_simple_list_set_item_selected (GtkSimpleList *simple_list, gint row, gboolean selection) 


Setting of specified row selection property. 


void gtk_simple_list_select_all (GtkSimpleList *simple_list) 


In all modes except browse mode, select all rows. 


void gtk_simple_list_unselect_all (GtkSimpleList *simple_list) 


in all modes except browse mode, deselect all rows 


6.102.2 Function Documentation 
6.102.2.1 gint gtk_simple_list_append (GtkSimpleList x simple_list, gchar x text[ ]) 


Append an element a the end of the simple list. 


Parameters: 


— simple_list : a GtkSimpleList 


< text : a text element 


Returns: 


Row number 


Since 


LIMO R1 


6.102.2.2 void gtk_simple_list_clear (GtkSimpleList x clist) 


Clear the entire simple list. 
Parameters: 

— simple_list : a GtkSimpleList 
Returns: 

void 
Since 


LIMO RI 
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6.102.2.3 GtkSimpleListStyle gtk_simple_list_get_style (GtkSimpleList x simple_list) 


Returns the style of the text. 


Parameters: 


— simple_list : a GtkSimpleList 


Returns: 


a GtkSimpleListStyle 


Since 


LIMO R1 


6.102.2.4 GType gtk_simple_list_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


Since 


LIMO R1 


6.102.2.5 gint gtk_simple_list_insert (GtkSimpleList x simple_list, gint row, gchar x text[ ]) 
Insert an element at the specified row of the simple list. 


Parameters: 
— simple_list : a GtkSimpleList 
<— row : Row number 


< text : Text node 


Returns: 


new simple list widget 


Since 


LIMO R1 


6.102.2.6 gboolean gtk_simple_list_is_item_selected (GtkSimpleList x simple_list, gint row) 


Create a new simple list. 


Parameters: 


— simple_list : a GtkSimpleList 
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<— row : which row want to select 


Returns: 


TRUE if the specified row is 


Since 


LIMO R1 


6.102.2.7 GtkWidget» gtk_simple_list_new (GtkSimpleListStyle style, gint columns) 
Create a new simple list. 


Parameters: 


— style : a GtkSimpleListStyle 


— columns : number of colums in the simplelist 


Returns: 


new simple list widget 


Since 


LIMO R1 


6.102.2.8 gint gtk_ simple list_prepend (GtkSimpleList x simple_list, gchar x text[ ]) 
Append an element a the starting of the simple list. 


Parameters: 
— simple_list : a GtkSimpleList 


< text : a text element 


Returns: 


Row number 


Since 


LIMO R1 


6.102.2.9 void gtk_simple_list_remove (GtkSimpleList « simple_list, gint row) 
removes row at index row 


Parameters: 
— simple_list : a GtkSimpleList 


<— row : row number, u want to remove 
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Returns: 
void 
Since 


LIMO R1 


6.102.2.10 void gtk_simple_list_select_all (GtkSimpleList x simple_list) 


In all modes except browse mode, select all rows. 
Parameters: 
— simple_list : a GtkSimpleList 
Returns: 
void 
Since 


LIMO R1 


6.102.2.11 void gtk_simple_list_set_item_selected (GtkSimpleList x simple_list, gint row, gboolean 
selection) 


Setting of specified row selection property. 


Parameters: 


— simple_list : a GtkSimpleList 
— row : row number 
— selection : TRUE or FALSE 


Returns: 
void 
Since 


LIMO R1 


6.102.2.12 void gtk_simple_list_set_style (GtkSimpleList x simple_list, GtkSimpleListStyle style) 


Sets the style. 


Parameters: 
— simple_list : a GtkSimpleList 
— style cd: a GtkSimpleListStyle 
Returns: 
void 
Since 


LIMO R1 
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6.102.2.13 void gtk_simple_list_unselect_all (GtkSimpleList x simple_list) 


in all modes except browse mode, deselect all rows 


Parameters: 


— simple_list : a GtkSimpleList 


Returns: 


void 


Since 


LIMO RI 
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6.103 GtkSoftkeyBar 


6.103.1 Detailed Description 


This Custom widget provides Softkey Bar functionality for Mobile GUI applications. 


GtkDialog «dialog; 
dialog = (GTK_DIALOG)gtk_dialog_new(); 


dialog->vbox = gtk_vbox_new (FALSE, 0); 
gtk_container_add (GTK_CONTAINER (dialog), dialog->vbox) ; 
gtk_widget_show (dialog->vbox) ; 


// crate sofft key 

dialog->softkey = gtk_softkey_bar_new(); 

gtk_box_pack_end (GTK_BOX (dialog->vbox), dialog->softkey, FALSE, FALSE, 0); 
gtk_widget_show (dialog->softkey); 


Since 


LIMO R1 


Data Structures 


e struct _GtkSoftkeyBar 
GtkSoftkeyBar widget defines softkey. 


e struct _GtkSoftkeyBarClass 
Gtk Softkey Bar Class. 


Typedefs 


e typedef guintl6 GtkSoftkeyCode 
typedef guint16 SoftkeyCode; 


e typedef gint(* GtkSoftkeyCallback )(GtkWidget «widget, GtkSoftkeyPosition softkey_position, 
gpointer data) 


softkey callback function 


Enumerations 


e enum GtkSoftkeyPosition { LEFT_SOFTKEY, CENTER _SOFTKEY, RIGHT_SOFTKEY, 
SOFTKEY_NUM } 


enumerator of softkey position 


e enum GtkSoftkeyActionType { SOFTKEY_MENU = 1, SOFTKEY_CALLBACK } 


enumerator of softkey action type 
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Functions 


GType gtk _softkey_bar_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


GtkWidget * gtk_softkey_bar_new (void) 
Constructor function for GtkSoftkeyBar. 


void gtk_softkey_bar_set_softkey (GtkSoftkeyBar x*softkey, GtkSoftkeyPosition position, gchar 
*softkey_name, GtkWidget *softkey_icon, GtkSoftkeyActionType softkey_action_type, gpointer 
action, gpointer user_data) 


Set a softkey. 


gboolean gtk_softkey_bar_get_softkey (GtkSoftkeyBar xsoftkey, GtkSoftkeyPosition position, 
gchar **softkey_name, GtkWidget **softkey_icon, GtkSoftkeyActionType *softkey_action_type, 
gpointer «action, gpointer «user_data) 


Get softkey information. 


gint gtk_softkey_bar_get_softkey_number (GtkSoftkeyBar softkey) 


Get the number of softkeys. 


void gtk_softkey_bar_reset_softkey (GtkSoftkeyBar x*softkey, GtkSoftkeyPosition position) 


Resets a softkey. 


void gtk_softkey_bar_reset_softkey_all (GtkSoftkeyBar *softkey) 
Resets all softkey. 


GtkSoftkeyCode gtk_softkey_bar_get_keycode (GtkSoftkeyBar «softkey, GtkSoftkeyPosition posi- 
tion) 


Returns SoftkeyCode value. 


6.103.2 Typedef Documentation 


6.103.2.1 typedef gint(« GtkSoftkeyCallback)(GtkWidget «widget, GtkSoftkeyPosition 


softkey_position, gpointer data) 


softkey callback function 


6.103.2.2 typedef guint16 GtkSoftkeyCode 


typedef guint16 SoftkeyCode; 


6.103.3 Enumeration Type Documentation 


6.103.3.1 enum GtkSoftkeyActionType 


enumerator of softkey action type 


The style of softkey actions being set. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


806 Module Documentation 


Enumerator: 


SOFTKEY MENU menu type 
SOFTKEY_CALLBACK callback type 


6.103.3.2 enum GtkSoftkeyPosition 
enumerator of softkey position 


Enumerator: 
LEFT_SOFTKEY left softkey 
CENTER_SOFTKEY center softkey 
RIGHT_SOFTKEY right softkey 
SOFTKEY_NUM the number of softkey 


6.103.4 Function Documentation 


6.103.4.1 GtkSoftkeyCode gtk_softkey_bar_get_keycode (GtkSoftkeyBar x softkey, 
GtkSoftkeyPosition position) 


Returns SoftkeyCode value. 


Parameters: 


— softkey a soft key bar. 


— position position of softkey bar. 


Returns: 


Softkey code value. 


Since 


LIMO RI 


6.103.4.2 gboolean gtk_softkey_bar_get_softkey (GtkSoftkeyBar x softkey, GtkSoftkeyPosition 
position, gchar xx softkey_name, GtkWidget x* softkey_icon, GtkSoftkeyActionType x 
softkey_action_type, gpointer x action, gpointer x user_data) 


Get softkey information. 


Parameters: 


— softkey a soft key bar. 

— position position of soft key bar. 
> softkey name. 

> softkey icon. 

— softkey action type. 


— gtkmenu. 
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— callback function. 


Returns: 


if it gets, return TRUE. 


Since 


LIMO RI 


6.103.4.3 gint gtk_softkey_bar_get_softkey_number (GtkSoftkeyBar x softkey) 


Get the number of softkeys. 


Parameters: 


— softkey a soft key bar. 


Returns: 


the number of soft keys. 


Since 


LIMO R1 


6.103.4.4 GType gtk_softkey_bar_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


6.103.4.5 GtkWidget» gtk_softkey_bar_new (void) 


Constructor function for GtkSoftkeyBar. 


Returns: 


a new GtkWidget. 


Since 


LIMO RI 


6.103.4.6 void gtk_softkey_bar_reset_softkey (GtkSoftkeyBar x softkey, GtkSoftkeyPosition 
position) 


Resets a softkey. 
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Parameters: 
— softkey a soft key bar. 


< position position of softkey bar. 


Since 


LIMO R1 


6.103.4.7 void gtk_softkey_bar_reset_softkey_all (GtkSoftkeyBar x softkey) 


Resets all softkey. 


Parameters: 


— softkey a soft key bar. 


Since 


LIMO R1 


6.103.4.8 void gtk_softkey_bar_set_softkey (GtkSoftkeyBar x softkey, GtkSoftkeyPosition 
position, gchar * softkey_name, GtkWidget x softkey_icon, GtkSoftkeyActionType 
softkey_action_type, gpointer action, gpointer user_data) 


Set a softkey. 


Parameters: 
— softkey a soft key bar. 
< position position of soft key bar. 
— softkey name. 
— softkey icon. 
<— softkey action type. 
— gtkmenu. 


< callback function. 


Since 


LIMO R1 
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6.104 GtkSpin 


6.104.1 Detailed Description 


This GTKSpin widget is enhanced for mobile environment with LEFT/RIGHT key Navigation support. 


Figure 6.24: GtkSpin 


Code Example 


Widget* spin ; 

spin = gtk_spin_new(); 
gtk_spin_add(spin, spintext); 
gtk_widget_show(spin) ; 


Since 


LIMO R1 


Data Structures 


e struct _GtkSpin 
GtkSpin class. 


e struct _GtkSpinClass 
GtkSpin class. 


e struct _GtkSpin 
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GtkSpin class. 


e struct _GtkSpinClass 
GtkSpin class. 


Functions 


e GType gtk_spin_get_type (void) G_GNUC_CONST 


This Fuction returns GType. 


e GtkWidget * gtk_spin_new (void) 


Create spin widget. 


e void gtk_spin_add (GtkSpin *spin, gchar *spintext) 
Add text to spin. 


e void gtk_spin_set_wrap (GtkSpin *spin, gboolean wrap) 


Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or 
lower limit of the range is exceeded. 


e void gtk_spin_insert (GtkSpin *spin, gchar *spintext, guint index) 


Insert the text of GtkSpin to specified index. 


e void gtk_spin_remove (GtkSpin «spin, guint index) 


Remove the text of specified index of GtkSpin. 


e void gtk_spin_remove_all (GtkSpin *spin) 
Remove all text of GtkSpin. 


e void gtk_spin_set (GtkSpin «spin, gchar *spintext, guint index) 
Set the text of specified index of GtkSpin. 


e void gtk_spin_set_selection_index (GtkSpin «spin, guint index) 


Set Selected index to GtkSpin. 


e gchar * gtk_spin_get (GtkSpin «spin, guint index) 
Return the text of specified index GtkSpin. 


e gchar x gtk_spin_get_selection (GtkSpin *spin) 


Return Selected text to GtkSpin. 


e guint gtk_spin_get_selection_index (GtkSpin *spin) 


Return Selected index to GtkSpin. 


e guint gtk_spin_get_count (GtkSpin *spin) 
Return The number of added text to GtkSpin. 
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6.104.2 Function Documentation 
6.104.2.1 void gtk_spin_add (GtkSpin x spin, gchar x spintext) 


Add text to spin. 


Parameters: 
— spin GtkSpin 


— spintext gchar return void 


Since 


LIMO R1 


6.104.2.2 gchar « gtk_spin_get (GtkSpin + spin, guint index) 


Return the text of specified index GtkSpin. 


Parameters: 
< spin GtkSpin 


< index guint 


Returns: 


The text of specified index 


Since 


LIMO RI 


6.104.2.3 guint gtk_spin_get_count (GtkSpin + spin) 


Return The number of added text to GtkSpin. 


Parameters: 


— spin GtkSpin 


Returns: 


the number of added GtkSpin. 


Since 


LIMO RI 
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6.104.2.4 gchar « gtk_spin_get_selection (GtkSpin + spin) 


Return Selected text to GtkSpin. 
Parameters: 

spin [in] GtkSpin 
Returns: 

selected text 


Since 


LIMO RI 


6.104.2.5 guint gtk_spin_get_selection_index (GtkSpin x spin) 
Return Selected index to GtkSpin. 
Parameters: 
— spin GtkSpin 
Returns: 
selection index 


Since 


LIMO R1 


6.104.2.6 GType gtk_spin_get_type (void) 


This Fuction returns GType. 
Returns: 

GType Type 
Since 


LIMO R1 


6.104.2.7 void gtk_spin_insert (GtkSpin * spin, gchar x spintext, guint index) 


Insert the text of GtkSpin to specified index. 


Parameters: 

— spin GtkSpin 

— spintext gchar 

< index index return void 
Since 


LIMO RI 
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6.104.2.8 GtkWidget « gtk_spin_new (void) 
Create spin widget. 


Returns: 


spin widget. 


Since 


LIMO R1 


6.104.2.9 void gtk_spin_remove (GtkSpin x spin, guint index) 
Remove the text of specified index of GtkSpin. 


Parameters: 
— spin GtkSpin 


< index index 


Returns: 


void 


Since 


LIMO R1 


6.104.2.10 void gtk_spin_remove_all (GtkSpin x spin) 
Remove all text of GtkSpin. 


Parameters: 


— spin GtkSpin 


Returns: 


void 


Since 


LIMO RI 


6.104.2.11 void gtk_spin_set (GtkSpin x spin, gchar x spintext, guint index) 
Set the text of specified index of GtkSpin. 


Parameters: 
< spin GtkSpin 


— spintext gchar 
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< index index 


Returns: 


void 


Since 


LIMO RI 


6.104.2.12 void gtk_spin_set_selection_index (GtkSpin * spin, guint index) 
Set Selected index to GtkSpin. 


Parameters: 


< index specifies the index 


Returns: 


void 


Since 


LIMO R1 


6.104.2.13 void gtk_spin_set_wrap (GtkSpin x spin, gboolean wrap) 
Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or 
lower limit of the range is exceeded. 


Rolling is default value, and can not be rolling by setting the rolling value. 


Parameters: 
< spin GtkSpin 


— wrap a flag indicating if wrapping behavior is performed. return void 


Since 


LIMO R1 
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6.105 GtkSymbolDialog 


6.105.1 Detailed Description 


This Custom dialog widget displays set of symbols/letters in the Grid fashion and provides option to navi- 
gate, provides option to select one value from set of displayed items. 


Figure 6.25: GtkSymbolDialog 


static gboolean 
softkey_cb_select_and_back (GtkWidget «widget, GtkSoftkeyPosition position, gpointer data) 
{ 


gint y ; 

gchar xstr; 

gint response; 
GtkWidget *window; 


window = GTK_WIDGET (data) ); 


window = get_symbol_dialog(); 

gtk_symbol_dialog_set_symbol (GTK_SYMBOL_DIALOG (window), 
symboll_table,size_symboll); 

response = gtk_dialog_run (GTK_DIALOG (window) ); 


str = (gchar *)gtk_symbol_dialog_get_text (GTK_SYMBOL_DIALOG (window), &y) ; 
g_printf ("\n\n\n>>>>>>>>> $s (%d)\n\n\n\n\n",str,y); 


gtk_widget_destroy (window) ; 


int main(int argc, char **argv) 
{ 

GtkWidget «dialog; 

GtkWidget x*frame; 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


816 Module Documentation 


GtkWidget x*vbox; 


window = gtk_window_new (GTK_WINDOW_TOPLEVEL) ; 
gtk_window_set_title (GTK_WINDOW (window), "Dialogs"); 


form = gtk_form_new (TRUE); 
gtk_main_window_add_form(GTK_MAIN_WINDOW (window) , GIK_FORM (form) ) ; 
gtk_form_set_title(GTK_FORM(form), "Symbol Dialog"); 


gtk_form_add_softkey (GTK_FORM(form), LEFT_SOFTKEY, "Invoke Dialog", NULL, 
SOFTKEY_CALLBACK, softkey_cb_select_and_back, window); 


return 0; 


) 


Since 


LIMO R1 


Data Structures 


e struct _GtkSymbolDialog 


GtkSymbolDialog instance structure. 


e struct _GtkSymbolDialogClass 


GtkSymbolDialogClass instance structure. 


Functions 


e GType gtk_symbol_dialog_get_type (void) G_GNUC_CONST 
This Fuction returns GType. 


e GtkWidget * gtk_symbol_dialog_new (gchar xstr, guint current_pos, guint max_length) 
Create symbol dialog widget. 


G_CONST_RETURN gchar « gtk_symbol_dialog_get_text (GtkSymbolDialog *symbol_window, 
gint xposition) 


Return the string of GtkSymbolDialog. 


e gboolean gtk _symbol_dialog_set_symbol (GtkSymbolDialog *symbol_window, gchar **symbol, 
gint symbol_size) 


Set the symbol image. 


6.105.2 Function Documentation 


6.105.2.1 G_CONST_RETURN gcharx gtk_symbol_dialog_get_text (GtkSymbolDialog x 
symbol_window, gint x position) 


Return the string of GtkSymbolDialog. 


Parameters: 


— widget widget that GtkSymbolDialog 
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Returns: 


The symbol dialog string 


Since 


LIMO R1 


6.105.2.2 GType gtk_symbol_dialog_get_type (void) 


This Fuction returns GType. 


Returns: 


GType Type 


Since 


LIMO RI 


6.105.2.3 GtkWidget gtk_symbol_dialog_new (gchar x str, guint current_pos, guint max_length) 
Create symbol dialog widget. 


Returns: 


symbol dialog widget. 


Since 


LIMO RI 


6.105.2.4 gboolean gtk_symbol_dialog_set_symbol (GtkSymbolDialog x symbol_window, gchar xx 
symbol, gint symbol_size) 


Set the symbol image. 


Parameters: 


— dialog GtkSymbolDialog 
— symbol symbol stock icon name 


— symbol_size size of symbol 


Returns: 


TRUE when function success 


Since 


LIMO R1 
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6.106 GdkWindow 


6.106.1 Detailed Description 
Modified for 
LIMO RI 


Functions 


e void gdk_window_enable_wm_redirection (GdkWindow «window, gboolean enable) 


Enables/ Disables Window Resize and Movement calls to Window Manager. 


6.106.2 Function Documentation 


6.106.2.1 void gdk_window_enable_wm_redirection (GdkWindow * window, gboolean enable) 


Enables/ Disables Window Resize and Movement calls to Window Manager. 


By WM redirection is enabled. This mainly used to avoid flickering caused by multips drawing process. 


Parameters: 


— window a GdkWindow 


— enable, if TRUE, WM redirection will be enabled. All window Resize, Movements will be redi- 
rected to WM. 


Returns: 


void 


Since 


LIMO R1 
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6.107 GdkEvents 
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6.108 Input Method 


Modules 


GtkIMModule 
This file declares the structures and functions of GtkIMModule. 


GtkIMContext 


GtkIMContext is base class for input method contexts. 


GtkIMMultiContext 


GtkIMMultiContext is an input method context supporting multiple, loadable input methods. 


GtkIMContextMultitab 
Through this IMContext implementation, English characters can be inputted through 3X4 mobile key pad. 
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6.109 GtkIMModule 


6.109.1 Detailed Description 


This file declares the structures and functions of GtkIMModule. 


Functions 


e void _gtk_im_module_list (const GtkIMContextInfo ***contexts, guint *n_contexts) 


List all available types of input method context. 


e GtkIMContext * _gtk_im_module_create (const gchar *context_id) 


Create an IM context of a type specified by the string ID (context_id). 


e const gchar * _gtk_im_module_get_default_context_id (const gchar xlocale) 


Return the context_id of the best IM context type for the given locale ID. 


6.109.2 Function Documentation 


6.109.2.1 GtkIMContext« _gtk_im_module_create (const gchar x context_id) 


Create an IM context of a type specified by the string ID (context_id). 


Parameters: 


context_id [in] the context ID for the context type to create 


Returns: 


value: a newly created input context of or , or NULL if that could not be created, a newly created 
GtkIMContextMultitab. 


6.109.2.2 const gchar* _gtk_im_module_get_default_context_id (const gchar x locale) 


Return the context_id of the best IM context type for the given locale ID. 


Parameters: 


locale [in] a locale id in the form ’en_US’ 


Returns: 


the context ID (will never be NULL) the value is newly allocated and must be freed with g_free(). 


6.109.2.3 void _gtk_im_module_list (const GtkIMContextInfo xxx contexts, guint x n_contexts) 


List all available types of input method context. 
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Parameters: 


contexts [in] location to store an array of pointers to GtkIMContextInfo this array should be freed 
with g_free() when you are finished. The structures it points are statically allocated and should 
not be modified or freed. 


n_contexts [in] the length of the array stored in 
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6.110 GtkIMContext 


6.110.1 Detailed Description 


GtkIMContext is base class for input method contexts. 


This documentaion shows extension of GtkIMContext for mobile platform. GTK defaultly supports loading 
multiple input methods through GtkIMMulticontext. gtk_im_context_get_module_property() and gtk_- 
im_context_set_module_property() functions represents handling each property of the input method mod- 
ule. Each input method has it’s own properties such as "active-input-mode", "supported-modes" and so on. 
Module property list can be queried using gtk_im_context_multitab_get_module_property_list() function. 


GtkIMContext* multi_context; 
multi_context = gtk_im_multicontext_get_singleton_instance()j; 


// get current active input mode string 

g_value_init (&value, G_TYPE_STRING) ; 

gtk_im_context_get_module_property (multi_context, "active-input-mode-string", $value); 
str = g_value_get_string (&value); 


g_print ("current input mode : %s\n", str); 


//get the current active input mode ID. 
g_value_init (&value, G_TYPE_INT); 
gtk_im_context_get_module_property (multi_context, "active-input-mode", value); 


// set current input mode , input modes are represented by each input mode 
g_value_init (&vlaue, G_TYPE_ INT); 
g_value_set_uint (value, AUTOMATIC_CAPITALIZATION_MODE); 


gtk_im_context_set_module_property ( gtk_im_multi_context_get_activate_im(multi_context), "active-input-n 


And there is also extension known as "notify_im_context" signal. each input method changes their current 
property status itself. then, this "notify_im_context" signal send current changed property, therefore you 
can write code like this : 


Initailize noitfy_im_context signal : 


//signal connet to GtkIMContext change notification 
g_signal_connect (multi_context, "notify _im context", G_CALLBACK(notify_im _context_cb), NULL); 


callback signal : 


void notify_im_context_cb (GtkIMContext *context, GParamSpec *pspec, gpointer pointer) 
{ 
GValue value = {0}; 


if (strcmp (pspec->name, "active-input-mode") == 0 ) 
{ 
g_value_init (&value, G_TYPE_STRING) ; 


gtk_im_context_get_module_property (multi_context, "active-input-mode-string", $value); 
str = g_value_get_string (&value); 
g_print ("input mode changed : %s\n", g_value_get_string (value)); 


g_vaule_unset (value); 


each GtkIMContext has its own properties; see property names and types for more information 
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Modified for 
LIMO RI 


Data Structures 


e struct _GtkIMContext 


GtkIMContext instance structure. 


e struct _GtkIMContextClass 


GtkIMContext instance class structure. 


Functions 


e void gtk_im_context_set_client_window (GtkIMContext «context, GdkWindow *window) 


Set the client window for the input context; this is the GdkWindow in which the input appears. 


e void gtk _im_context_get_preedit_string (GtkIMContext context, gchar str, PangoAttrList 
+xattrs, gint *cursor_pos) 


Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. 


e gboolean gtk_im_context_filter_keypress (GtkIMContext «context, GdkEventKey *event) 


Allow an input method to internally handle key press and release events. 


e void gtk_im_context_focus_in (GtkIMContext *context) 


Notify the input method that the widget to which this input context corresponds has gained focus. 


e void gtk_im_context_focus_out (GtkIMContext *context) 


Notify the input method that the widget to which this input context corresponds has lost focus. 


e void gtk_im_context_reset (GtkIMContext *context) 


Notify the input method that a change such as a change in cursor position has been made. 


e void gtk_im_context_set_cursor_location (GtkIMContext «context, GdkRectangle xarea) 


Notify the input method that a change in cursor position has been made. 


e void gtk_im_context_set_use_preedit (GtkIMContext «context, gboolean use_preedit) 


Sets whether the IM context should use the preedit string to display feedback. 


e void gtk_im_context_set_surrounding (GtkIMContext *context, const gchar text, gint len, gint 
cursor_index) 


Sets surrounding context around the insertion point and preedit string. 


e gboolean gtk_im_context_get_surrounding (GtkIMContext «context, gchar **text, gint *cursor_- 
index) 


Retrieves context around the insertion point. 


e gboolean gtk_im_context_delete_surrounding (GtkIMContext «context, gint offset, gint n_chars) 
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Asks the widget that the input context is attached to to delete characters around the cursor position by 
emitting the GtkIMContext: :delete_surrounding signal. 


e void gtk_im_context_get_module_property (GtkIMContext *context, const gchar *property_name, 
GValue «value) 


extension for input mode 


e void gtk_im_context_set_module_property (GtkIMContext «context, const gchar *property_name, 
const GValue *value) 


Sets a property to the current input method. 


e int gtk_im_context_get_module_property_list (GtkIMContext «context, GParamSpec **param_- 
spec) 
Gets the IM Context Module properties Spec list. 


Variables 


e void(*« _GtkIMContextClass::input_mode_changed )(GtkIMContext «context, const gchar *input_- 
method, const gchar *input_mode) 


LIMO R1. 


e void(*« _GtkIMContextClass::cursor_moved )(GtkIMContext «context, gint prev_pos, gint moved_- 
pos) 


LIMO extension for cursor position. 


e void(« _GtkIMContextClass::get_module_property )(GtkIMContext context, const gchar 
*property_name, GValue *value) 


LIMO extension for input mode property. 


e void(« _GtkIMContextClass::set_module_property )(GtkIMContext context, const gchar 
*property_name, const GValue «value) 


LIMO extension for input mode property. 


e gint(* _GtkIMContextClass::get_module_property_list )(GtkIMContext context, GParamSpec 
**paramspec) 


LIMO extension for input mode property. 


6.110.2 Function Documentation 


6.110.2.1 gboolean gtk_im_context_delete_surrounding (GtkIM Context x context, gint offset, gint 
n_chars) 


Asks the widget that the input context is attached to to delete characters around the cursor position by 
emitting the GtkIMContext::delete_surrounding signal. 


Note that offset and n_chars are in characters not in bytes which differs from the usage other places in 
GtkIMContext. 


In order to use this function, you should first call gtk_im_context_get_surrounding() to get the current 
context, and call this function immediately afterwards to make sure that you know what you are deleting. 
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You should also account for the fact that even if the signal was handled, the input context might not have 
deleted all the characters that were requested to be deleted. 


This function is used by an input method that wants to make subsitutions in the existing text in response to 
new input. It is not useful for applications. 
Parameters: 

context [in] a GtkIMContext 

offset [in] offset from cursor position in chars; a negative value means start before the cursor. 


n_chars [in] number of characters to delete. 


Returns: 


TRUE if the signal was handled. 


6.110.2.2  gboolean gtk_im_context_filter_keypress (GtkIMContext x context, GdkEventKey * 
event) 


Allow an input method to internally handle key press and release events. 


Tf this function returns TRUE, then no further processing should be done for this key event. 


Parameters: 
context [in] a GtkIMContext 


event [in] the key event 


Returns: 


TRUE if the input method handled the key event. 


6.110.2.3 void gtk_im_context_focus_in (GtkIMContext x context) 


Notify the input method that the widget to which this input context corresponds has gained focus. 


The input method may, for example, change the displayed feedback to reflect this change. 


Parameters: 


context [in] a GtkIMContext 


Returns: 


void 


6.110.2.4 void gtk_im_context_focus_out (GtkIMContext x context) 


Notify the input method that the widget to which this input context corresponds has lost focus. 


The input method may, for example, change the displayed feedback or reset the contexts state to reflect this 
change. 
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Parameters: 


context [in] a GtkIMContext 


Returns: 


void 


6.110.2.5 void gtk_im_context_get_module_property (GtkIMContext x context, const gchar x 
property_name, GValue x value) 


extension for input mode 

Get a property from the current input method. it is similar to g_object_get_property(), but get a property 
of the tcurrent input method or GtkIMMulticontext. 

Parameters: 


context [in] a GtkIMContext 
property_name [in] property name of the current input method or GtkIMMulticontext 


value [out] property value of the current input method or GtkIMMulticontext 


Returns: 


void 


Since 


LIMO RI 


6.110.2.6 int gtk_im_context_get_module_property_list (GtkIMContext x context, GParamSpec 
xx param_spec) 


Gets the IM Context Module properties Spec list. 


Parameters: 


context [in] a GtkIMContext 
param_spec [out] GParamSpec, that will be filled . 


Returns: 


Returns the parameter count. 


Since 


LIMO R1 


6.110.2.7 void gtk_im_context_get_preedit_string (GtkIMContext x context, gchar ** str, 
PangoAttrList xx attrs, gint x cursor_pos) 


Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. 


This string should be displayed inserted at the insertion point. 
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Parameters: 
context [in] a GtkIMContext 
str [out] location to store the retrieved string. The string retrieved must be freed with g_free(). 


attrs [out] location to store the retrieved attribute list. When you are done with this list, you must 
unreference it with pango_attr_list_unref() 


— cursor_poss location to store position of cursor (in characters) within the preedit string. 


Returns: 


void 


6.110.2.8 gboolean gtk_im_context_get_surrounding (GtkIMContext x context, gchar xx text, gint 
x cursor_index) 


Retrieves context around the insertion point. 


Input methods typically want context in order to constrain input text based on existing text; this is important 
for languages such as Thai where only some sequences of characters are allowed. 


This function is implemented by emitting the GtkIMContext::retrieve_surrounding signal on the input 
method; in response to this signal, a widget should provide as much context as is available, up to an 
entire paragraph, by calling gtk_im_context_set_surrounding(). Note that there is no obligation for a wid- 
get to respond to the retrieve_surrounding signal, so input methods must be prepared to function without 
context. 


Parameters: 
context [in] a GtkIMContext 


text [out] location to store a UTF-8 encoded string of text holding context around the insertion point. 
If the function returns TRUE, then you must free the result stored in this location with g_free(). 


cursor_index [out] location to store byte index of the insertion cursor within text. 


Returns: 


TRUE if surrounding text was provided; in this case you must free the result stored in «text. 


6.110.2.9 void gtk_im_context_reset (GtkIMContext « context) 


Notify the input method that a change such as a change in cursor position has been made. 


This will typically cause the input method to clear the preedit state. 


Parameters: 


context [in] a GtkIMContext 


Returns: 


void 
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6.110.2.10 void gtk_im_context_set_client_window (GtkIMContext « context, GdkWindow = 
window) 


Set the client window for the input context; this is the Gdk Window in which the input appears. 

This window is used in order to correctly position status windows, and may also be used for purposes 
internal to the input method. 

Parameters: 


context [in] a GtkIMContext 


window [in] the client window. This may be NULL to indicate that the previous client window no 
longer exists. 


Returns: 


void 


6.110.2.11 void gtk_im_context_set_cursor_location (GtkIMContext x context, GdkRectangle « 
area) 


Notify the input method that a change in cursor position has been made. 
The location is relative to the client window. 
Parameters: 

context [in] a GtkIMContext 


area [in] new location 


Returns: 


void 


6.110.2.12 void gtk_im_context_set_module_property (GtkIMContext « context, const gchar x 
property_name, const GValue x value) 


Sets a property to the current input method. 


it is similar to g_object_set_property(), but sets a property for the current input method or GtkIMMulticon- 
text. 


Parameters: 


context [in] a GtkIMContext 
property_name [in] property name of the current input method or GtkIMMiulticontext 


value [in] a GValue 
Returns: 
void 


Since 


LIMO R1 
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6.110.2.13 void gtk_im_context_set_surrounding (GtkIMContext x context, const gchar * text, gint 
len, gint cursor_index) 


Sets surrounding context around the insertion point and preedit string. 

This function is expected to be called in response to the GtkIMContext::retrieve_surrounding signal, and 
will likely have no effect if called at other times. 

Parameters: 


context [in] a GtkIMContext 


text [in] text surrounding the insertion point, as UTF-8. the preedit string should not be included 
within text. 


len [in] the length of text, or -1 if text is nul-terminated 


cursor_index [in] the byte index of the insertion cursor within text. 


Returns: 


void 


6.110.2.14 void gtk_im_context_set_use_preedit (GtkIMContext x context, gboolean use_preedit) 


Sets whether the IM context should use the preedit string to display feedback. 


If use_preedit is FALSE (default is TRUE), then the IM context may use some other method to display 
feedback, such as displaying it in a child of the root window. 


Parameters: 


context [in] a GtkIMContext 
use_preedit [in] whether the IM context should use the preedit string. 


Returns: 
void 
6.110.3 Variable Documentation 


6.110.3.1  void(* _GtkIMContextClass::cursor_moved)(GtkIMContext «context, gint prev_pos, 
gint moved_pos) [inherited] 


LIMO extension for cursor position. 


6.110.3.2 void(« _GtkIMContextClass::get_module_property)(GtkIMContext «context, const 
gchar *property_name, GValue xvalue) [inherited] 


LIMO extension for input mode property. 


6.110.3.3 gint(« _GtkIMContextClass::get_module_property_list)(GtkIMContext «context, 
GParamSpec «*paramspec) [inherited] 


LIMO extension for input mode property. 
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6.110.3.4 void(* _GtkIMContextClass: :input_mode_changed)(GtkIMContext «context, const 
gchar xinput_method, const gchar xinput_mode) [inherited] 


LIMO RI. 


use notify_im_context 


6.110.3.5  void(* _GtkIMContextClass::set_module_property)(GtkIMContext «context, const 
gchar «property_name, const GValue *value) [inherited] 


LIMO extension for input mode property. 
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6.111 GtkIMMultiContext 


6.111.1 Detailed Description 


GtkIMMultiContext is an input method context supporting multiple, loadable input methods. 


Modified for 
LIMO RI 


Data Structures 


e struct _GtkIMMulticontext 


GtkIMMulticontext instance structure. 


e struct _GtkIMMulticontextClass 


GtkIMMulticontext instance class structure. 


Functions 


e GtkIMContext x gtk_im_multicontext_new (void) 


Creates a new GtkIMMulticontext. 


e void gtk_im_multicontext_append_menuitems (GtkIMMulticontext context, GtkMenuShell 
*menushell) 


Add menuitems for various available input methods to a menu; the menuitems, when selected, will switch 
the input method for the context and the global default input method. 


e GtkIMContext x gtk_im_multicontext_get_singleton_instance (void) 


Returns the reference of Singleton IM Multicontext instance. 


e gboolean gtk_im_ multi context_activate_im (GtkIMMulticontext *context, char *im_module_- 
name) 


Activates the Input Method module. 


e GtkIMContext x gtk_im_multi_context_get_activate_im (GtkIMMulticontext *context) 


Activates the Input Method module. 


6.111.2 Function Documentation 


6.111.2.1 gboolean gtk_im_multi_context_activate_im (GtkIMMulticontext x context, char x 
im_module_name) 


Activates the Input Method module. 


Parameters: 


— context a GtkIMMulticontext 
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< im_module_name IM Module Name 


Returns: 


Returns TRUE if the module name is valid and activated. 


Since 


LIMO R1 


6.111.2.2  GtkIMContext* gtk_im_multi_context_get_activate_im (GtkIMMulticontext « context) 


Activates the Input Method module. 


Parameters: 


< context a GtkIMMulticontext 


< im_module_name IM Module Name 


Returns: 


Returns the active IM Context. 


Since 


LIMO R1 


6.111.2.3 void gtk_im_multicontext_append_menuitems (GtkIMMulticontext * context, 
GtkMenuShell « menushell) 


Add menuitems for various available input methods to a menu; the menuitems, when selected, will switch 
the input method for the context and the global default input method. 


Parameters: 


— context a GtkIMMulticontext 
< menushell a GtkMenuShell 


Returns: 


void 


6.111.2.4 GtkIMContext* gtk_im_multicontext_get_singleton_instance (void) 
Returns the reference of Singleton IM Multicontext instance. 


Returns: 


a singleton GtkIMMulticontext instance reference 


Since 


LIMO RI 
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6.111.2.5  GtkIMContext* gtk_im_multicontext_new (void) 
Creates a new GtkIMMulticontext. 


Returns: 


a new GtkIMMulticontext. 
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6.112 GtkIMContextMultitab 


6.112.1 Detailed Description 


Through this IMContext implementation, English characters can be inputted through 3X4 mobile key pad. 


This is based on GtkIMMultiContext, which allows "compose" based on sequences of characters. But 
instead the character sequences are defined by lists of characters for a key, so that repeated pressing of the 
same key can cycle through the possible output characters, with automatic choosing of the character after 
a time delay. 


Since 


LIMO R1 


Data Structures 


e struct _GtkIMContextMultitab 


GtkIMContextMultitab instance structure. 


e struct _GtkIMContextMultitabClass 


GtkIMContextMultitab instance class structure. 


Enumerations 


e enum GtkMultitabInputMode 
Supported Multitab input Modes Types. 


e enum GtkMultitabInputLanguage 
Supported Multitab Languages Types. 


Functions 


e void im_module_init (GTypeModule «module) 


intialise the Imcontext multi tab module 


e void im_module_exit (void) 


Exit from the Imcontext multi tab module. 


e void im_module_list (const GtkIMContextInfo «contexts, int *n_contexts) 


Get the Im context module list and count. 


GtkIMContext * gtk_im_context_multitab_new (void) 


Create a new imcontext multi tab context. 
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6.112.2 Enumeration Type Documentation 
6.112.2.1 enum GtkMultitabInputLanguage 


Supported Multitab Languages Types. 


6.112.2.2 enum GtkMultitabInputMode 


Supported Multitab input Modes Types. 


6.112.3 Function Documentation 


6.112.3.1 GtkIMContext* gtk_im_context_multitab_new (void) 


Create a new imcontext multi tab context. 


Returns: 


a newly created multi context 


Since 


LIMO RI 


6.112.3.2 void im_module_exit (void) 
Exit from the Imcontext multi tab module. 


Returns: 


void 


Since 


LIMO R1 


6.112.3.3 void im_module_init (GTypeModule x module) 
intialise the Imcontext multi tab module 


Parameters: 


< module : a GTypeModule. 


Returns: 


void 


Since 


LIMO R1 
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6.112.3.4 void im_module_list (const GtkIMContextInfo ««« contexts, int x n_contexts) 
Get the Im context module list and count. 


Parameters: 
=> contexts : a GtkIMContextInfo. 


— n_contexts : number if im contexts 


Returns: 


void 


Since 


LIMO RI 
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Chapter 7 


Data Structure Documentation 


7.1  _GdkEventCaseMovement Struct Reference 


#include <gdkevents.h> 


7.1.1 Detailed Description 


GDK Case movement event structure. 


Data Fields 


e GdkEventType type 
Event type: GDK_CASE_MOVEMENT. 


e GdkCaseMovementState state 


Case Movement State. 


7.1.2 Field Documentation 
7.1.2.1 GdkEventType _GdkEventCaseMovement::type 


Event type: GDK_CASE_MOVEMENT. 


7.1.2.2 GdkCaseMovementState _GdkEventCaseMovement::state 


Case Movement State. 


The documentation for this struct was generated from the following file: 


e gdkevents.h 
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7.2  _GtkAdjustment Struct Reference 


#include <gtkadjustment.h> 


7.2.1 Detailed Description 


GtkAdjustment instance stucture. 


The documentation for this struct was generated from the following file: 


e gtkadjustment.h 
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7.3 _GtkAdjustmentClass Struct Reference 


#include <gtkadjustment.h> 


7.3.1 Detailed Description 


GtkAdjustment instance class stucture. 


The documentation for this struct was generated from the following file: 


e gtkadjustment.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.4 _GtkAlignment Struct Reference 


#include <gtkalignment.h> 


7.4.1 Detailed Description 


GtkAlignment interface structure. 


The documentation for this struct was generated from the following file: 


e gtkalignment.h 
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7.5 _GtkAlignmentClass Struct Reference 843 


7.5  _GtkAlignmentClass Struct Reference 


#include <gtkalignment.h> 


7.5.1 Detailed Description 


GtkAlignment interface class structure. 


The documentation for this struct was generated from the following file: 


e gtkalignment.h 
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7.6 _GtkAspectFrame Struct Reference 


#include <gtkaspectframe.h> 


7.6.1 Detailed Description 


GtkAspectFrame instance structure. 


The documentation for this struct was generated from the following file: 


e gtkaspectframe.h 
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7.7 _GtkAspectFrameClass Struct Reference 


#include <gtkaspectframe.h> 


7.7.1 Detailed Description 


GtkAspectFrame instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkaspectframe.h 
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7.8 _GtkBin Struct Reference 


#include <gtkbin.h> 


7.8.1 Detailed Description 


GtkBin instance structure. 


The documentation for this struct was generated from the following file: 


e gtkbin.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.9 _GtkBinClass Struct Reference 


tinclude <gtkbin.h> 


7.9.1 Detailed Description 


GtkBin instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkbin.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.10 _GtkBindingSet Struct Reference 


#include <gtkbindings.h> 


7.10.1 Detailed Description 


GtkBindingSet instance structure. 


The documentation for this struct was generated from the following file: 


e gtkbindings.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.11  _GtkBox Struct Reference 


#include <gtkbox.h> 


7.11.1 Detailed Description 


GtkBox instance structure. 


The documentation for this struct was generated from the following file: 


e gtkbox.h 
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7.12 _GtkBoxClass Struct Reference 


tinclude <gtkbox.h> 


7.12.1 Detailed Description 


GtkBox instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkbox.h 
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7.13 _GtkButton Struct Reference 


#include <gtkbutton.h> 


7.13.1 Detailed Description 


GtkButton interface structure. 


The documentation for this struct was generated from the following file: 


e gtkbutton.h 
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7.14 _GtkButtonClass Struct Reference 


#include <gtkbutton.h> 


7.14.1 Detailed Description 


GtkButton interface class structure. 


The documentation for this struct was generated from the following file: 


e gtkbutton.h 
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7.15 _GtkCellLayoutIface Struct Reference 


#include <gtkcelllayout.h> 


7.15.1 Detailed Description 


GtkCellLayout interface structure. 


The documentation for this struct was generated from the following file: 


e gtkcelllayout.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.16 _GtkCellRenderer Struct Reference 


#include <gtkcellrenderer.h> 


7.16.1 Detailed Description 


GtkCellRenderer instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrenderer.h 
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7.17 _GtkCellRendererAccel Struct Reference 


#include <gtkcellrendereraccel.h> 


7.17.1 Detailed Description 


GtkCellRendererAccel instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrendereraccel.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.18 _GtkCellRendererClass Struct Reference 


#include <gtkcellrenderer.h> 


7.18.1 Detailed Description 


GTK Native GtkCellRenderer instance class structure. 


Data Fields 


e void(* editing_canceled )(GtkCellRenderer xcell) 


This signal gets emitted when the user cancels the process of editing a cell. 


e void(x* editing_started )(GtkCellRenderer x*cell, GtkCellEditable «editable, const gchar xpath) 


This signal gets emitted when a cell starts to be edited. 


7.18.2 Field Documentation 
7.18.2.1 void(« _GtkCellRendererClass::editing_canceled)(GtkCellRenderer xcell) 


This signal gets emitted when the user cancels the process of editing a cell. 


For example, an editable cell renderer could be written to cancel editing when the user presses Escape. See 
also: gtk_cell_renderer_editing_canceled() 


Parameters: 


cell [in] the object which received the signal 


7.18.2.2 void(« _GtkCellRendererClass: :editing_started)(GtkCellRenderer «cell, GtkCellEditable 
«editable, const gchar «path) 


This signal gets emitted when a cell starts to be edited. 


The indended use of this signal is to do special setup on editable, e.g. adding a GtkEntryCompletion or 
setting up additional columns in a GtkComboBox. 


Note that GTK+ doesn't guarantee that cell renderers will continue to use the same kind of widget for 
editing in future releases, therefore you should check the type of editable before doing any specific setup, 
as in the following example: 


static void 

text_editing_started (GtkCellRenderer x*cell, 
GtkCellEditable «editable, 
const gchar *path, 
gpointer data) 

{ 

if (GTK_IS_ENTRY (editable) ) 

{ 
GtkEntry x*entry = GTK_ENTRY (editable); 


// ... create a GtkEntryCompletion 
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gtk_entry_set_completion (entry, completion); 
} 
} 


Parameters: 
cell [in] the object which received the signal 
editable [in] the GtkCellEditable 
path [in] the path identifying the edited cell 


Returns: 


void 


The documentation for this struct was generated from the following file: 


e gtkcellrenderer.h 
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7.19 _GtkCellRendererPixbuf Struct Reference 


tinclude <gtkcellrendererpixbuf.h> 


7.19.1 Detailed Description 


GtkCellRendererPixbuf instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrendererpixbuf.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.20 _GtkCellRendererPixbufClass Struct Reference 859 


7.20 _GtkCellRendererPixbufClass Struct Reference 


#include <gtkcellrendererpixbuf.h> 


7.20.1 Detailed Description 


GTK Native GtkCellRendererPixbuf instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrendererpixbuf.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.21 _GtkCellRendererProgress Struct Reference 


#include <gtkcellrendererprogress.h> 


7.21.1 Detailed Description 


GtkCellRendererProgress instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrendererprogress.h 
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7.22 _GtkCellRendererProgressClass Struct Reference 


#include <gtkcellrendererprogress.h> 


7.22.1 Detailed Description 


GtkCellRendererProgress instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrendererprogress.h 
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7.23 _GtkCellRendererText Struct Reference 


#include <gtkcellrenderertext.h> 


7.23.1 Detailed Description 


GtkCellRendererText instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrenderertext.h 
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7.24 _GtkCellRendererTextClass Struct Reference 


#include <gtkcellrenderertext.h> 


7.24.1 Detailed Description 


GTK Native GtkCellRendererText instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrenderertext.h 
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7.25 _GtkCellRendererToggle Struct Reference 


#include <gtkcellrenderertoggle.h> 


7.25.1 Detailed Description 


GtkCellRendererToggle instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcellrenderertoggle.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.26 _GtkCellRendererToggleClass Struct Reference 


#include <gtkcellrenderertoggle.h> 


7.26.1 Detailed Description 


GtkCellRendererToggle instance class structure. 


Data Fields 


e void(* toggled )(GtkCellRendererToggle *cell_renderer_toggle, const gchar xpath) 
The toggled signal is emitted when the cell is toggled. 


7.26.2 Field Documentation 


7.26.2.1 void(« _GtkCellRendererToggleClass::toggled)(GtkCellRendererToggle 
*cell_renderer_toggle, const gchar xpath) 


The toggled signal is emitted when the cell is toggled. 


Parameters: 


cell_renderer_toggle [in] the object which received the signal 


path [in] string representation of GtkTreePath describing the event location 


Returns: 


void 
The documentation for this struct was generated from the following file: 


e gtkcellrenderertoggle.h 
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7.27 _GtkCellView Struct Reference 


#include <gtkcellview.h> 


7.27.1 Detailed Description 


GtkCell View instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcellview.h 
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7.28 _GtkCellViewClass Struct Reference 


#include <gtkcellview.h> 


7.28.1 Detailed Description 


GtkCell View instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkcellview.h 
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7.29  _GtkCheckButton Struct Reference 


#include <gtkcheckbutton.h> 


7.29.1 Detailed Description 


GtkCheckButton interface structure. 


The documentation for this struct was generated from the following file: 


e gtkcheckbutton.h 
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7.30 —GtkCheckButtonClass Struct Reference 


#include <gtkcheckbutton.h> 


7.30.1 Detailed Description 


GtkCheckButton interface class structure. 


The documentation for this struct was generated from the following file: 


e gtkcheckbutton.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.31 _GtkCheckMenultem Struct Reference 


#include <gtkcheckmenuitem.h> 


7.31.1 Detailed Description 


GtkCheckMenultem instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcheckmenuitem.h 
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7.32 _GtkCheckMenultemClass Struct Reference 


#include <gtkcheckmenuitem.h> 


7.32.1 Detailed Description 


GTK Native GtkCheckMenultem instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkcheckmenuitem.h 
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872 Data Structure Documentation 


7.33 _GtkColorChooser Struct Reference 


#include <gtkcolorchooser.h> 


7.33.1 Detailed Description 


GtkColorChooser instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcolorchooser.h 
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7.34 _GtkColorChooserClass Struct Reference 


#include <gtkcolorchooser.h> 


7.34.1 Detailed Description 


GtkColorChooserClass instance structure. 


Data Fields 


e GtkWidgetClass parent_class 


parent class 


e void(* move_cursor )(GtkColorChooser *colorchooser, GtkMovementStep step, gint count, 
gboolean extend_selection) 


e void(* value_changed )(GtkColorChooser *colorchooser) 
This function is called when value is changed. 


7.34.2 Field Documentation 
7.34.2.1 GtkWidgetClass _GtkColorChooserClass::parent_class 


parent class 


7.34.2.2 void(« _GtkColorChooserClass::move_cursor)(GtkColorChooser «colorchooser, 
GtkMovementStep step, gint count, gboolean extend_selection) 


This function is called when cursor moves. 
Parameters: 


— colorchooser the object which received the signal. 
< step enum GtkMovementStep 

< count move count 

— extend_selection extend selction 


7.34.2.3 void(« _GtkColorChooserClass::value_changed)(GtkColorChooser «colorchooser) 


This function is called when value is changed. 


Parameters: 


— colorchooser GtkColorChooser 
The documentation for this struct was generated from the following file: 


e gtkcolorchooser.h 
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7.35 _GtkComboBox Struct Reference 


#include <gtkcombobox.h> 


7.35.1 Detailed Description 


GtkComboBox instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcombobox.h 
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7.36  _GtkComboBoxClass Struct Reference 


#include <gtkcombobox.h> 


7.36.1 Detailed Description 


GtkComboBox instance calss structure. 


The documentation for this struct was generated from the following file: 


e gtkcombobox.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.37 _GtkContainer Struct Reference 


#include <gtkcontainer.h> 


7.37.1 Detailed Description 


GtkContainer instance structure. 


The documentation for this struct was generated from the following file: 


e gtkcontainer.h 
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7.38 _GtkContainerClass Struct Reference 


#include <gtkcontainer.h> 


7.38.1 Detailed Description 


GtkContainer instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkcontainer.h 
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7.39 _GtkDialog Struct Reference 


#include <gtkdialog.h> 


7.39.1 Detailed Description 


GtkDialog instance structure. 


Data Fields 


e GtkWidget » titlelabel 
title label 


e GtkWidget * content_area 


content area 


e GtkWidget « softkey 


softkey area 


e gint dialog _width 


softkey area 


7.39.2 Field Documentation 
7.39.2.1 GtkWidgetx _GtkDialog::titlelabel 


title label 


7.39.2.2 GtkWidget« _GtkDialog::content_area 


content area 


7.39.2.3 GtkWidget« _GtkDialog::softkey 


softkey area 


7.39.2.4 gint GtkDialog::dialog_width 


softkey area 


The documentation for this struct was generated from the following file: 


e gtkdialog.h 
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7.40 _GtkDialogClass Struct Reference 


#include <gtkdialog.h> 


7.40.1 Detailed Description 


GtkDialogClass class. 


The documentation for this struct was generated from the following file: 


e gtkdialog.h 
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7.441 _GtkDrawingArea Struct Reference 


#include <gtkdrawingarea.h> 


7.41.1 Detailed Description 


GtkDrawingArea instance structure. 


The documentation for this struct was generated from the following file: 


e gtkdrawingarea.h 
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7.42 _GtkDrawingAreaClass Struct Reference 


#include <gtkdrawingarea.h> 


7.42.1 Detailed Description 


GtkDrawingArea instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkdrawingarea.h 
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7.43 _GtkEditableClass Struct Reference 


#include <gtkeditable.h> 


7.43.1 Detailed Description 


GtkEditable instance class structure. 


Data Fields 


e void(* insert_text )(GtkEditable «editable, const gchar text, gint length, gint xposition) 


This signal is emitted when text is inserted into the widget by the user. 


e void(* delete_text )(GtkEditable «editable, gint start_pos, gint end_pos) 


This signal is emitted when text is deleted from the widget by the user. 


e void(« changed )(GtkEditable editable) 


Indicates that the user has changed the contents of the widget. 


7.43.2 Field Documentation 


7.43.2.1  void(* _GtkEditableClass: :insert_text)(GtkEditable «editable, const gchar «text, gint 
length, gint «position) 
This signal is emitted when text is inserted into the widget by the user. 


The default handler for this signal will normally be responsible for inserting the text, so by connecting to 
this signal and then stopping the signal with gtk_signal_emit_stop(), it is possible to modify the inserted 
text, or prevent it from being inserted entirely. 


Parameters: 
editable [in] the object which received the signal. 
text [in] the new text to insert. 
length [in] the length of the new text, in bytes, or -1 if new_text is nul-terminated 


position [in] the position, in characters, at which to insert the new text. this is an in-out parameter. 
After the signal emission is finished, it should point after the newly inserted text.. 


7.43.2.2 void(« _GtkEditableClass::delete_text)(GtkEditable «editable, gint start_pos, gint 
end_pos) 


This signal is emitted when text is deleted from the widget by the user. 


The default handler for this signal will normally be responsible for inserting the text, so by connecting to 
this signal and then stopping the signal with gtk_signal_emit_stop(), it is possible to modify the inserted 
text, or prevent it from being inserted entirely. The start_pos and end_pos parameters are interpreted as for 
gtk_editable_delete_text() 
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Parameters: 
editable [in] the object which received the signal. 
start_pos [in] the starting position. 


end_pos [in] the end position. 


7.43.2.3 void(« _GtkEditableClass::changed)(GtkEditable «editable) 


Indicates that the user has changed the contents of the widget. 


Parameters: 


editable [in] the object which received the signal. 


The documentation for this struct was generated from the following file: 


e gtkeditable.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


884 Data Structure Documentation 


7.44 _GtkEntry Struct Reference 


#include <gtkentry.h> 


7.44.1 Detailed Description 


GtkEntry instance structure. 


Data Fields 


e gchar x preset_string 


For preset string. 


e gboolean presetted 


TRUE when preset_string is setted. 


e guintin_drag: 1 


LIMO R1 


e GtkWidget * popup_menu 
LIMO R1 


e gint dnd position 


LIMO R1 


7.44.2 Field Documentation 
7.44.2.1 gcharx _GtkEntry::preset_string 
For preset string. 

preset_string 

7.44.2.2 gboolean _GtkEntry::presetted 


TRUE when preset_string is setted. 


7.44.2.3 guint GtkEntry::in_drag 


LIMO R1 


7.44.2.4 GtkWidget _GtkEntry::popup_menu 


LIMO R1 
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7.44.2.5 gint GtkEntry::dnd_position 


LIMO R1 


The documentation for this struct was generated from the following file: 


e gtkentry.h 
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7.45  _GtkEntryClass Struct Reference 


#include <gtkentry.h> 


7.45.1 Detailed Description 


GTK Native GtkEntry instance class structure. 


Data Fields 


e void(* activate )(GtkEntry *entry) 


Function pointer for activate signal. 


void(x* cut_clipboard )(GtkEntry *entry) 
LIMO R1 


void(* copy_clipboard )(GtkEntry xentry) 
LIMO R1 


void(* paste_clipboard )(GtkEntry entry) 
LIMO R1 


void(* toggle_overwrite )(GtkEntry *entry) 
LIMO R1 


void(* populate_popup )(GtkEntry *entry, GtkMenu *menu) 
LIMO R1 


void(* input_mode_changed )(GtkEntry *entry, const gchar *input_method, const gchar +input_- 
mode) 


IME notification call back function. 


7.45.2 Field Documentation 
7.45.2.1 void(« _GtkEntryClass::activate)(GtkEntry «entry) 


Function pointer for activate signal. 


7.45.2.2 void(« _GtkEntryClass::cut_clipboard)(GtkEntry entry) 


LIMO RI 


7.45.2.3 void(« _GtkEntryClass::copy_clipboard)(GtkEntry «entry) 


LIMO R1 
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7.45.2.4 void(« _GtkEntryClass::paste_clipboard)(GtkEntry «*entry) 


LIMO RI 


7.45.2.5  void(x* _GtkEntryClass::toggle_overwrite)(GtkEntry xentry) 


LIMO R1 


7.45.2.6 void(« _GtkEntryClass::populate_popup)(GtkEntry «entry, GtkMenu «menu) 


LIMO R1 


7.45.2.7 void(« _GtkEntryClass::input_mode_changed)(GtkEntry «entry, const gchar 
xinput_method, const gchar «input_mode) 


IME notification call back function. 


Parameters: 
entry [in] a entry 
input_method [in] object name 


inputmode [in] IME current input mode LIMO R1 


The documentation for this struct was generated from the following file: 


e gtkentry.h 
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7.46 _GtkEntryCompletion Struct Reference 


#include <gtkentrycompletion.h> 


7.46.1 Detailed Description 


GtkEntryCompletion instance structure. 


The documentation for this struct was generated from the following file: 


e gtkentrycompletion.h 
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7.47 _GtkEntryCompletionClass Struct Reference 


#include <gtkentrycompletion.h> 


7.47.1 Detailed Description 


GtkEntryCompletion instance class structure. 


Data Fields 


e gboolean(* match_selected )(GtkEntryCompletion *completion, GtkTreeModel *model, Gtk- 
Treelter xiter) 


Gets emitted when a match from the list is selected. 


e void(* action_activated )(GtkEntryCompletion *completion, gint index_) 


Gets emitted when an action is activated. 


e gboolean(* insert_prefix )(GtkEntryCompletion *completion, const gchar xprefix) 


Gets emitted when the inline autocompletion is triggered. 


7.47.2 Field Documentation 


7.47.2.1 gboolean(« _GtkEntryCompletionClass::match_selected)(GtkEntryCompletion 
«completion, GtkTreeModel «model, GtkTreelter xiter) 

Gets emitted when a match from the list is selected. 

The default behaviour is to replace the contents of the entry with the contents of the text column in the row 

pointed to by iter. 

Parameters: 


completion [in] the object which received the signal 
model [in] the GtkTreeModel containing the matches 


iter [in] a GtkTreelter positioned at the selected match 


Returns: 


TRUE if the signal has been handled 


7.47.2.2  void(* _GtkEntryCompletionClass::action_activated)(GtkEntryCompletion «completion, 
gint index_) 


Gets emitted when an action is activated. 


Parameters: 


completion [in] the object which received the signal 


index_ [in] the index of the activated action 
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Returns: 


void 


7.47.2.3 gboolean(« _GtkEntryCompletionClass: :insert_prefix)(GtkEntryCompletion 
«completion, const gchar «prefix) 

Gets emitted when the inline autocompletion is triggered. 

The default behaviour is to make the entry display the whole prefix and select the newly inserted part. 

Applications may connect to this signal in order to insert only a smaller part of the prefix into the entry - 

e.g. the entry used in the GtkFileChooser inserts only the part of the prefix up to the next ’/’. 

Parameters: 


completion [in] the object which received the signal 


prefix [in] the common prefix of all possible completions 


Returns: 


TRUE if the signal has been handled 
The documentation for this struct was generated from the following file: 


e gtkentrycompletion.h 
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7.48 _GtkEventBox Struct Reference 


#include <gtkeventbox.h> 


7.48.1 Detailed Description 


GtkEventBox instance structure. 


The documentation for this struct was generated from the following file: 


e gtkeventbox.h 
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7.49 —GtkEventBoxClass Struct Reference 


#include <gtkeventbox.h> 


7.49.1 Detailed Description 


GtkEventBox instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkeventbox.h 
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7.50  _GtkFixed Struct Reference 


tinclude <gtkfixed.h> 


7.50.1 Detailed Description 


GtkFixed instance structure. 


The documentation for this struct was generated from the following file: 


e gtkfixed.h 
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7.51 _GtkFixedClass Struct Reference 


tinclude <gtkfixed.h> 


7.51.1 Detailed Description 


GtkFixed instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkfixed.h 
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7.52 _GtkFocusBin Struct Reference 


#include <gtkfocusbin.h> 


7.52.1 Detailed Description 


GtkFocusBin instance structure. 


The documentation for this struct was generated from the following file: 


e gtkfocusbin.h 
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7.53 _GtkFocusBinClass Struct Reference 


#include <gtkfocusbin.h> 


7.53.1 Detailed Description 


GtkFocusBinClass instance structure. 


The documentation for this struct was generated from the following file: 


e gtkfocusbin.h 
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7.54 _GtkForm Struct Reference 


#include <gtkform.h> 


7.54.1 Detailed Description 


GtkForm represents a scene of GUI application. 


Data Fields 


e GtkWidget * softkeybar 
softkeybar is a GtkSoftkeyBar widget. 


e gchar x title 
This is a title of GtkForm. 


e GtkWidget * icon 
This is a icon of GtkForm. 


7.54.2 Field Documentation 
7.54.2.1 GtkWidgetx _GtkForm::softkeybar 


softkeybar is a GtkSoftkeyBar widget. 


This is created at creation time of GtkForm only if gtk_form_new’s has_softkey parameter is TRUE. 


7.54.2.2 gchar» _GtkForm::title 


This is a title of GtkForm. 
title is set by gtk_form_set_title(). 


When gtk_mobilewindow_set_current_form() is called this variable 
GtkMobileWindow::form_title. 


7.54.2.3 GtkWidget» _GtkForm::icon 


This is a icon of GtkForm. 
icon is set by gtk_form_set_icon(). 


When — gtk_mobilewindow_set_current_form() is called this variable 
GtkMobileWindow::form_icon. 


The documentation for this struct was generated from the following file: 


e gtkform.h 


is copied 


is copied 


to 


to 
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7.55 _GtkFormattedEntry Struct Reference 


#include <gtkformattedentry.h> 


7.55.1 Detailed Description 


GtkFormattedEntry instance structure. 


The documentation for this struct was generated from the following file: 


e gtkformattedentry.h 
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7.56 _GtkFormattedEntryClass Struct Reference 


#include <gtkformattedentry.h> 


7.56.1 Detailed Description 


GtkFormattedEntry instance class structure. 


Data Fields 


e void(* move_cursor )(GtkFormattedEntry *formatted_entry, GtkMovementStep step, gint 
count) 


e void(* backspace )(GtkFormattedEntry *formatted_entry) 


This function is called when clear key is pressed. 


e void(* move_field )(GtkFormattedEntry *formatted_entry, gint current_field_index) 


This function is called when field moves. 


e void(* value_changed )(GtkFormattedEntry *formatted_entry) 


This function is called when value is changed. 


7.56.2 Field Documentation 


7.56.2.1 void(« _GtkFormattedEntryClass::move_cursor)(GtkFormattedEntry «formatted_entry, 
GtkMovementStep step, gint count) 


This function is called when cursor moves. 


Parameters: 
— formatted_entry the object which received the signal. 
— step enum GtkMovementStep 


< count move count LIMO R1 


7.56.2.2 void(« _GtkFormattedEntryClass::backspace)(GtkFormattedEntry «formatted_entry) 


This function is called when clear key is pressed. 


Parameters: 


— formatted_entry the object which received the signal. LIMO R1 
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7.56.2.3 void(« _GtkFormattedEntryClass::move_field)(GtkFormattedEntry «formatted_entry, 
gint current_field_index) 


This function is called when field moves. 


Parameters: 


— formatted_entry the object which received the signal. 
— current_field_index current field index. LIMO R1 


7.56.2.4 void(« _GtkFormattedEntryClass::value_changed)(GtkFormattedEntry 
*formatted_entry) 


This function is called when value is changed. 


Parameters: 


— formatted_entry GtkFormattedEntry LIMO R1 
The documentation for this struct was generated from the following file: 


e gtkformattedentry.h 
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7.57 _GtkFormClass Struct Reference 


#include <gtkform.h> 


7.57.1 Detailed Description 


GtkForm Class. 


The documentation for this struct was generated from the following file: 


e gtkform.h 
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7.58 _GtkFrame Struct Reference 


tinclude <gtkframe.h> 


7.58.1 Detailed Description 


GtkFrame instance structure. 


The documentation for this struct was generated from the following file: 


e gtkframe.h 
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7.59 _GtkFrameClass Struct Reference 


#include <gtkframe.h> 


7.59.1 Detailed Description 


GtkFrame instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkframe.h 
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7.60  _GtkHBox Struct Reference 


#include <gtkhbox.h> 


7.60.1 Detailed Description 


GtkHBox instance structure. 


The documentation for this struct was generated from the following file: 


e gtkhbox.h 
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7.61  _GtkHBoxClass Struct Reference 


#include <gtkhbox.h> 


7.61.1 Detailed Description 


GtkHBox instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkhbox.h 
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7.62 _GtkHScale Struct Reference 


#include <gtkhscale.h> 


7.62.1 Detailed Description 


GtkHScale instance structure. 


The documentation for this struct was generated from the following file: 


e gtkhscale.h 
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7.63 _GtkHScaleClass Struct Reference 


#include <gtkhscale.h> 


7.63.1 Detailed Description 


GtkHScale instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkhscale.h 
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7.64 _GtkHScrollbar Struct Reference 


#include <gtkhscrollbar.h> 


7.64.1 Detailed Description 


GtkHScrollbar instance structure. 


The documentation for this struct was generated from the following file: 


e gtkhscrollbar.h 
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7.65  _GtkHScrollbarClass Struct Reference 


#include <gtkhscrollbar.h> 


7.65.1 Detailed Description 


GtkHScrollbar instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkhscrollbar.h 
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7.66 _GtkIconFactory Struct Reference 


#include <gtkiconfactory.h> 


7.66.1 Detailed Description 


GtkIconFactory instance structure. 


The documentation for this struct was generated from the following file: 


e gtkiconfactory.h 
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7.67 _GtkIconFactoryClass Struct Reference 


#include <gtkiconfactory.h> 


7.67.1 Detailed Description 


GtkIconFactory instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkiconfactory.h 
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7.68 _GtkIconTheme Struct Reference 


#include <gtkicontheme.h> 


7.68.1 Detailed Description 


GtkIconTheme instance structure. 


The documentation for this struct was generated from the following file: 


e gtkicontheme.h 
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7.69 _GtkIconThemeClass Struct Reference 


#include <gtkicontheme.h> 


7.69.1 Detailed Description 


GtkIconTheme instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkicontheme.h 
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7.70 _GtkIconView Struct Reference 


#include <gtkiconview.h> 


7.70.1 Detailed Description 


GtkIcon View instance structure. 


The documentation for this struct was generated from the following file: 


e gtkiconview.h 
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7.71 _GtkIconViewClass Struct Reference 


#include <gtkiconview.h> 


7.71.1 Detailed Description 


GtkIcon View instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkiconview.h 
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7.72 _GtkImage Struct Reference 


#include <gtkimage.h> 


7.72.1 Detailed Description 


GtkImage instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.73 _GtkImageAnimationData Struct Reference 


#include <gtkimage.h> 


7.73.1 Detailed Description 


GtkImageAnimationData instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.74 _GtkImageClass Struct Reference 


#include <gtkimage.h> 


7.74.1 Detailed Description 


GtkImage instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.75 _GtkImageIconNameData Struct Reference 


#include <gtkimage.h> 


7.75.1 Detailed Description 


GtkImagelconNameData instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.76 _GtkImagelconSetData Struct Reference 


tinclude <gtkimage.h> 


7.76.1 Detailed Description 


GtkImagelconSetData instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.77 _GtkImagelmageData Struct Reference 


tinclude <gtkimage.h> 


7.77.1 Detailed Description 


GtkImageImageData instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.78 _GtkImagePixbufData Struct Reference 


#include <gtkimage.h> 


7.78.1 Detailed Description 


GtkImagePixbufData instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.79 _GtkImagePixmapData Struct Reference 


#include <gtkimage.h> 


7.79.1 Detailed Description 


GtkImagePixmapData instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.80 _GtkImageStockData Struct Reference 


#include <gtkimage.h> 


7.80.1 Detailed Description 


GtkImageStockData instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimage.h 
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7.81 _GtkIMContext Struct Reference 


#include <gtkimcontext.h> 


7.81.1 Detailed Description 


GtkIMContext instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimcontext.h 
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7.82 


_GtkIMContextClass Struct Reference 


#include <gtkimcontext.h> 


7.82.1 Detailed Description 


GtkIMContext instance class structure. 


Data Fields 


void(* input_mode_changed )(GtkIMContext *context, const gchar *input_method, const gchar 
*input_mode) 
LIMO R1. 


void(* cursor_moved )(GtkIMContext «context, gint prev_pos, gint moved_pos) 


LIMO extension for cursor position. 


void(* get_module_property )(GtkIMContext *context, const gchar *property_name, GValue 
*value) 


LIMO extension for input mode property. 


void(* set_module_property )(GtkIMContext *context, const gchar *property_name, const GValue 
*value) 


LIMO extension for input mode property. 


gint(* get_module_property_list )(GtkIMContext «context, GParamSpec **paramspec) 


LIMO extension for input mode property. 


The documentation for this struct was generated from the following file: 


gtkimcontext.h 
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7.83 _GtkIMContextMultitab Struct Reference 


#include <gtkimcontextmultitab.h> 


7.83.1 Detailed Description 


GtkIMContextMultitab instance structure. 


Data Fields 


e gsize key_sequences_count 


Number of KeySequence struct instances. 


7.83.2 Field Documentation 
7.83.2.1  gsize _GtkIMContextMultitab::key_sequences_count 


Number of KeySequence struct instances. 


The documentation for this struct was generated from the following file: 


e gtkimcontextmultitab.h 
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7.84 _GtkIMContextMultitabClass Struct Reference 


#include <gtkimcontextmultitab.h> 


7.84.1 Detailed Description 


GtkIMContextMultitab instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkimcontextmultitab.h 
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7.85 _GtkIMMulticontext Struct Reference 


#include <gtkimmulticontext.h> 


7.85.1 Detailed Description 


GtkIMMulticontext instance structure. 


The documentation for this struct was generated from the following file: 


e gtkimmulticontext.h 
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7.86 _GtkIMMulticontextClass Struct Reference 


#include <gtkimmulticontext.h> 


7.86.1 Detailed Description 


GtkIMMulticontext instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkimmulticontext.h 
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7.87 _GtkIndicator Struct Reference 


#include <gtkindicator.h> 


7.87.1 Detailed Description 


GtkIndicator instance structure. 


The documentation for this struct was generated from the following file: 


e gtkindicator.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


932 Data Structure Documentation 


7.88 _GtkIndicatorClass Struct Reference 


#include <gtkindicator.h> 


7.88.1 Detailed Description 


GtkIndicator instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkindicator.h 
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7.89 _GtkItem Struct Reference 


#include <gtkitem.h> 


7.89.1 Detailed Description 


GtkItem instance structure. 


The documentation for this struct was generated from the following file: 


e gtkitem.h 
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7.90 _GtkItemClass Struct Reference 


#include <gtkitem.h> 


7.90.1 Detailed Description 


GtkItem instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkitem.h 
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7.91 _GtkLabel Struct Reference 


#include <gtklabel.h> 


7.91.1 Detailed Description 


GtkLabel instance structure. 


The documentation for this struct was generated from the following file: 


e gtklabel.h 
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7.92 _GtkLabelClass Struct Reference 


#include <gtklabel.h> 


7.92.1 Detailed Description 


GTK Native GtkLabel instance class structure. 


The documentation for this struct was generated from the following file: 


e gtklabel.h 
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7.93 _GtkLayout Struct Reference 


#include <gtklayout.h> 


7.93.1 Detailed Description 


GtkLayout instance structure. 


The documentation for this struct was generated from the following file: 


e gtklayout.h 
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7.94 _GtkLayoutClass Struct Reference 


#include <gtklayout.h> 


7.94.1 Detailed Description 


GtkLayout instance class structure. 


The documentation for this struct was generated from the following file: 


e gtklayout.h 
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7.95 _GtkListStore Struct Reference 


939 


7.95 _GtkListStore Struct Reference 


#include <gtkliststore.h> 


7.95.1 Detailed Description 


GtkListStore instance structure. 


The documentation for this struct was generated from the following file: 


e gtkliststore.h 
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7.96 _GtkListStoreClass Struct Reference 


#include <gtkliststore.h> 


7.96.1 Detailed Description 


GtkListStore instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkliststore.h 
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7.97 _GtkMainWindow Struct Reference 


#include <gtkmainwindow.h> 


7.97.1 Detailed Description 


GtkMainWindow is the toplevel frame window which can contain other widgets. 


GtkMainWindow has almost same functionalities as GtkWindow except that it has its own layout 
area(status and client area) and it has responsibility to manage its layout area 


Data Fields 


e GtkWidget * status_area 


Indicator, icon and title are packed in status_area. 


e GtkWidget * indicator 


Indicator widget. 


e GtkWidget x title_widget 
Title widget(GtkLabel can be used). 


e GtkWidget * default_icon 


default_icon is the icon of GtkMainWindow. 


e GtkWidget * form_icon 


form_icon is the icon of GtkForm. 


e GList x form_list 


form_list is a list of forms which are previously added by gtk_main_window_add_form(). 


7.97.2 Field Documentation 
7.97.2.1 GtkWidget» _GtkMainWindow::status_area 


Indicator, icon and title are packed in status_area. 


7.97.2.2 GtkWidget» _GtkMainWindow::indicator 


Indicator widget. 


7.97.2.3 GtkWidget» _GtkMainWindow::title_widget 


Title widget(GtkLabel can be used). 
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7.97.2.4 GtkWidgetx _GtkMainWindow::default_icon 


default_icon is the icon of GtkMainWindow. 


This member variable is set by gtk_main_window_set_default_icon(). 


7.97.2.5 GtkWidget» _GtkMainWindow::form_icon 


form_icon is the icon of GtkForm. 


This member variable is set when GtkForm is contained. gtk_main_window_set_current_form() does this. 


7.97.2.6 GList« _GtkMainWindow::form_list 


form_list is a list of forms which are previously added by gtk_main_window_add_form(). 


Forms are removed by calling gtk_main_window_remove_current_form(), gtk_main_window_remove_- 
form(), or gtk_main_window_remove_all_forms(). 


The documentation for this struct was generated from the following file: 


e gtkmainwindow.h 
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7.98 _GtkMainWindowClass Struct Reference 


#include <gtkmainwindow.h> 


7.98.1 Detailed Description 


GtkMainWindow Class. 


Data Fields 


e void(* compute_child_allocation )(GtkMainWindow «mw, GtkAllocation x*allocation) 


7.98.2 Field Documentation 


7.98.2.1 void(« _GtkMainWindowClass::compute_child_allocation)(GtkMainWindow «mv, 
GtkAllocation allocation) 


compute child allocation 


Parameters: 


<— mw main window 


— allocation allocation LIMO R1 
The documentation for this struct was generated from the following file: 


e gtkmainwindow.h 
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7.99 _GtkMenu Struct Reference 


#include <gtkmenu.h> 


7.99.1 Detailed Description 


GtkMenu instance structure. 


Data Fields 


e GtkAccelGroup * accel_group 
LIMO R1 


e GtkWidget * tearoff_window 
LIMO RI 


e GdkRegion * navigation_region 


When a submenu of this menu is popped up, motion in this region is ignored. 


e guint torn_off: 1 
LIMO R1 


7.99.2 Field Documentation 
7.99.2.1 GtkAccelGroup* _GtkMenu::accel_group 


LIMO R1 


7.99.2.2 GtkWidgetx _GtkMenu::tearoff_window 


LIMO R1 


7.99,2.3 GdkRegionx* _GtkMenu::navigation_region 


When a submenu of this menu is popped up, motion in this region is ignored. 


7.99.2.4 guint GtkMenu::torn_off 


LIMO RI 


The documentation for this struct was generated from the following file: 


e gtkmenu.h 
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7.100 _GtkMenuClass Struct Reference 


#include <gtkmenu.h> 


7.100.1 Detailed Description 


GTK Native GtkMenu instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkmenu.h 
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7.101 _GtkMenultem Struct Reference 


#include <gtkmenuitem.h> 


7.101.1 Detailed Description 


GtkMenultem instance structure. 


The documentation for this struct was generated from the following file: 


e gtkmenuitem.h 
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7.102  _GtkMenultemClass Struct Reference 


#include <gtkmenuitem.h> 


7.102.1 Detailed Description 


GTK Native GtkMenultem instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkmenuitem.h 
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7.103 _GtkMenuShell Struct Reference 


#include <gtkmenushell.h> 


7.103.1 Detailed Description 


GtkMenuShell instance structure. 


The documentation for this struct was generated from the following file: 


e gtkmenushell.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.104  _GtkMenuShellClass Struct Reference 


#include <gtkmenushell.h> 


7.104.1 Detailed Description 


GTK Native GtkMenuShell instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkmenushell.h 
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7.105 _GtkMessageBox Struct Reference 


#include <gtkmessagebox.h> 


7.105.1 Detailed Description 


GtkMessageBox class. 


Data Fields 


e GtkWidget x» title 
title label 


e GtkWidget * content 


content area 


7.105.2 Field Documentation 
7.105.2.1 GtkWidget» _GtkMessageBox::title 


title label 


7.105.2.2 GtkWidget _GtkMessageBox::content 


content area 


The documentation for this struct was generated from the following file: 


e gtkmessagebox.h 
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7.106 _GtkMessageBoxClass Struct Reference 


#include <gtkmessagebox.h> 


7.106.1 Detailed Description 


MessageBoxClass class. 


Data Fields 


e void(* response )(GtkMessageBox *messagebox, gint response_id) 


signal 


7.106.2 Field Documentation 


7.106.2.1 void(« _GtkMessageBoxClass::response)(GtkMessageBox *messagebox, gint 
response_id) 


signal 


The documentation for this struct was generated from the following file: 


e gtkmessagebox.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.107 _GtkMessageDialog Struct Reference 


#include <gtkmessagedialog.h> 


7.107.1 Detailed Description 


GtkMessageDialog instance structure. 


The documentation for this struct was generated from the following file: 


e gtkmessagedialog.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.108 _GtkMessageDialogClass Struct Reference 


#include <gtkmessagedialog.h> 


7.108.1 Detailed Description 


GtkMessageDialog instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkmessagedialog.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.109 _GtkMisc Struct Reference 


#include <gtkmisc.h> 


7.109.1 Detailed Description 


GtkMisc interface structure. 
These fields should be considered read-only. They should never be set by an application 


The documentation for this struct was generated from the following file: 


e gtkmisc.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.110 _GtkMiscClass Struct Reference 
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7.110  _GtkMiscClass Struct Reference 


#include <gtkmisc.h> 


7.110.1 Detailed Description 


GtkMisc interface class structure. 


The documentation for this struct was generated from the following file: 


e gtkmisc.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.111 _GtkNotebook Struct Reference 


#include <gtknotebook.h> 


7.111.1 Detailed Description 


GtkNotebook instance structure. 
There is added field related to a tab style. Another fields is not descriped. 


The documentation for this struct was generated from the following file: 


e gtknotebook.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.112 _GtkNotebookClass Struct Reference 


#include <gtknotebook.h> 


7.112.1 Detailed Description 


GtkNotebook instance class structure. 


The documentation for this struct was generated from the following file: 


e gtknotebook.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.113 _GtkObject Struct Reference 


#include <gtkobject.h> 


7.113.1 Detailed Description 


GtkObject instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkobject.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.114 _GtkObjectClass Struct Reference 
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7.114 _GtkObjectClass Struct Reference 


#include <gtkobject.h> 


7.114.1 Detailed Description 


GtkObject instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkobject.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.115 _GtkProgress Struct Reference 


#include <gtkprogress.h> 


7.115.1 Detailed Description 


GtkProgress stucture. 


The documentation for this struct was generated from the following file: 


e gtkprogress.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.116 _GtkProgressBar Struct Reference 
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7.116 _GtkProgressBar Struct Reference 


#include <gtkprogressbar.h> 


7.116.1 Detailed Description 


GtkProgressBar instance stucture. 


The documentation for this struct was generated from the following file: 


e gtkprogressbar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.1117 _GtkProgressBarClass Struct Reference 


#include <gtkprogressbar.h> 


7.117.1 Detailed Description 


GtkProgressBar instance Class structure. 


The documentation for this struct was generated from the following file: 


e gtkprogressbar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.118 _GtkProgressClass Struct Reference 
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7.118 _GtkProgressClass Struct Reference 


#include <gtkprogress.h> 


7.118.1 Detailed Description 


GtkProgress class stucture. 


The documentation for this struct was generated from the following file: 


e gtkprogress.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.119 _GtkRadioButton Struct Reference 


#include <gtkradiobutton.h> 


7.119.1 Detailed Description 


GtkRadioButton interface structure. 


The documentation for this struct was generated from the following file: 


e gtkradiobutton.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.120  _GtkRadioButtonClass Struct Reference 


#include <gtkradiobutton.h> 


7.120.1 Detailed Description 


GtkRadioButton interface class structure. 


The documentation for this struct was generated from the following file: 


e gtkradiobutton.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.121 _GtkRadioMenultem Struct Reference 


#include <gtkradiomenuitem.h> 


7.121.1 Detailed Description 


GtkRadioMenultem instance structure. 


The documentation for this struct was generated from the following file: 


e gtkradiomenuitem.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.122 _GtkRadioMenultemClass Struct Reference 


#include <gtkradiomenuitem.h> 


7.122.1 Detailed Description 


GTK Native GtkRadioMenultem instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkradiomenuitem.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.123 _GtkRange Struct Reference 


#include <gtkrange.h> 


7.123.1 Detailed Description 


GtkRange instance structure. 


The documentation for this struct was generated from the following file: 


e gtkrange.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.124 _GtkRangeClass Struct Reference 


tinclude <gtkrange.h> 


7.124.1 Detailed Description 


GtkRange instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkrange.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.1125 _GtkRcProperty Struct Reference 


#include <gtkrc.h> 


7.125.1 Detailed Description 


rc properties (structure forward declared in gtkstyle.h) 


The documentation for this struct was generated from the following file: 


e gtkrc.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.126 _GtkRcStyle Struct Reference 


#include <gtkrc.h> 


7.126.1 Detailed Description 


GtkRcStyle instance structure. 


The documentation for this struct was generated from the following file: 


e gtkrc.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.127 _GtkRcStyleClass Struct Reference 


#include <gtkrc.h> 


7.127.1 Detailed Description 


GtkRcStyle instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkrc.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.128 _GtkRequisition Struct Reference 
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7.128 _GtkRequisition Struct Reference 


#include <gtkwidget.h> 


7.128.1 Detailed Description 


A requisition is a desired amount of space which a widget may request. 


The documentation for this struct was generated from the following file: 


e gtkwidget.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.129 _GtkScale Struct Reference 


tinclude <gtkscale.h> 


7.129.1 Detailed Description 


GtkScale instance structure. 


The documentation for this struct was generated from the following file: 


e gtkscale.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.130 _GtkScaleClass Struct Reference 
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7.130  _GtkScaleClass Struct Reference 


tinclude <gtkscale.h> 


7.130.1 Detailed Description 


GtkScale instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkscale.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.131 _GtkScrollbar Struct Reference 


#include <gtkscrollbar.h> 


7.131.1 Detailed Description 


GtkScrollbar instance structure. 


The documentation for this struct was generated from the following file: 


e gtkscrollbar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.132 _GtkScrollbarClass Struct Reference 
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7.132 _GtkScrollbarClass Struct Reference 


#include <gtkscrollbar.h> 


7.132.1 Detailed Description 


GtkScrollbar instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkscrollbar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.133 _GtkScrolled Window Struct Reference 


#include <gtkscrolledwindow.h> 


7.133.1 Detailed Description 


scrolled window instance 


The documentation for this struct was generated from the following file: 


e gtkscrolledwindow.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.134 _GtkScrolledWindowClass Struct Reference 


tinclude <gtkscrolledwindow.h> 


7.134.1 Detailed Description 


scrolled window class 


Data Fields 


e void(* scroll_child )(GtkScrolledWindow x*scrolled_window, GtkScrollType scroll, gboolean hor- 
izontal) 


7.134.2 Field Documentation 


7.134.2.1  void(« _GtkScrolledWindowClass::scroll_child)(GtkScrolled Window *scrolled_window, 
GtkScrollType scroll, gboolean horizontal) 


The documentation for this struct was generated from the following file: 


e gtkscrolledwindow.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.135 _GtkSettings Struct Reference 


#include <gtksettings.h> 


7.135.1 Detailed Description 


GtkSettings instance structure. 


The documentation for this struct was generated from the following file: 


e gtksettings.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.136 _GtkSettingsClass Struct Reference 


#include <gtksettings.h> 


7.136.1 Detailed Description 


GtkSettings instance class structure. 


The documentation for this struct was generated from the following file: 


e gtksettings.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.137 _GtkSimpleList Struct Reference 


#include <gtksimplelist.h> 


7.137.1 Detailed Description 


GtkSimpleList instance structure. 


The documentation for this struct was generated from the following file: 


e gtksimplelist.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.138 _GtkSimpleListClass Struct Reference 
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7.138 _GtkSimpleListClass Struct Reference 


#include <gtksimplelist.h> 


7.138.1 Detailed Description 


GtkSimpleList instance structure. 


The documentation for this struct was generated from the following file: 


e gtksimplelist.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.139 _GtkSoftkeyBar Struct Reference 


#include <gtksoftkeybar.h> 


7.139.1 Detailed Description 


GtkSoftkeyBar widget defines softkey. 


It is inherited from GtkBin. 


Data Fields 


e SoftkeyDesc x softkey [SOFTKEY_NUM] 


softkey_area is a container for softkey_label(s) 


e gint num_softkey 


the number of softkey 


e GtkSoftkeyCode softkey_code [SOFTKEY_NUM] 
hard key value for softkey 


7.139.2 Field Documentation 
7.139.2.1 SoftkeyDesc* _GtkSoftkeyBar::softkey[SOFTKEY_NUM] 


softkey_area is a container for softkey_label(s) 


softkey description struct array 


7.139.2.2 gint GtkSoftkeyBar::num_softkey 


the number of softkey 


7.139.2.3 GtkSoftkeyCode _GtkSoftkeyBar::softkey_code[SOFTKEY_NUM] 


hard key value for softkey 


The documentation for this struct was generated from the following file: 


e gtksoftkeybar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.140 _GtkSoftkeyBarClass Struct Reference 


#include <gtksoftkeybar.h> 


7.140.1 Detailed Description 


Gtk Softkey Bar Class. 


Data Fields 


e void(* softkey_pressed )(GtkSoftkeyBar softkey, GdkEventKey xevent) 


signal callback function for "softkey_pressed" signal. 


e void(* left_softkey_pressed )(GtkSoftkeyBar «softkey, GdkEventKey xevent) 


e void(* center_softkey_pressed )(GtkSoftkeyBar «softkey, GdkEventKey xevent) 


e void(* right_softkey_pressed )(GtkSoftkeyBar «softkey, GdkEventKey xevent) 


7.140.2 Field Documentation 


7.140.2.1 void(* _GtkSoftkeyBarClass::softkey_pressed)(GtkSoftkeyBar «softkey, GdkEventKey 
*xevent) 


signal callback function for "softkey_pressed" signal. 


when softkey is pressed, "softkey_pressed" signal is emitted. 


7.140.2.2 void(« _GtkSoftkeyBarClass::left_softkey_pressed)(GtkSoftkeyBar «softkey, 
GdkEventKey event) 


7.140.2.3 void(« _GtkSoftkeyBarClass::center_softkey_pressed)(GtkSoftkeyBar «softkey, 
GdkEventKey event) 


7.140.2.4 void(« _GtkSoftkeyBarClass::right_softkey_pressed)(GtkSoftkeyBar «softkey, 
GdkEventKey event) 


The documentation for this struct was generated from the following file: 


e gtksoftkeybar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.141 _GtkSpin Struct Reference 


#include <gtkspin.h> 


7.141.1 Detailed Description 


GtkSpin class. 


The documentation for this struct was generated from the following file: 


e gtkspin.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.142 _GtkSpinClass Struct Reference 


tinclude <gtkspin.h> 


7.142.1 Detailed Description 


GtkSpin class. 


The documentation for this struct was generated from the following file: 


e gtkspin.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.143 _GtkStyle Struct Reference 


#include <gtkstyle.h> 


7.143.1 Detailed Description 


GtkStyle instance structure. 


The documentation for this struct was generated from the following file: 


e gtkstyle.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.144 _GtkStyleClass Struct Reference 
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7.144 _GtkStyleClass Struct Reference 


#include <gtkstyle.h> 


7.144.1 Detailed Description 


GtkStyle instance class structure. 


Data Fields 


e void(* realize )(GtkStyle *style) 


Initialize for a particular colormap/depth combination. 


e void(* unrealize )(GtkStyle *style) 


Clean up for a particular colormap/depth combination. 


7.144.2 Field Documentation 

7.144.2.1  void(« _GtkStyleClass::realize)(GtkStyle «style) 

Initialize for a particular colormap/depth combination. 

style->colormap/style->depth will have been set at this point. Will typically chain to parent. 
7.144.2.2 void(« _GtkStyleClass::unrealize)(GtkStyle style) 


Clean up for a particular colormap/depth combination. 
Will typically chain to parent. 


The documentation for this struct was generated from the following file: 


e gtkstyle.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.145 _GtkSymbolDialog Struct Reference 


#include <gtksymboldialog.h> 


7.145.1 Detailed Description 


GtkSymbolDialog instance structure. 


The documentation for this struct was generated from the following file: 


e gtksymboldialog.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.146 _GtkSymbolDialogClass Struct Reference 


#include <gtksymboldialog.h> 


7.146.1 Detailed Description 


GtkSymbolDialogClass instance structure. 


The documentation for this struct was generated from the following file: 


e gtksymboldialog.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.147 _GtkTable Struct Reference 


#include <gtktable.h> 


7.147.1 Detailed Description 


GtkTable instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktable.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.148 _GtkTableClass Struct Reference 


tinclude <gtktable.h> 


7.148.1 Detailed Description 


GtkTable instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktable.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.149 _GtkTextAppearance Struct Reference 


#include <gtktexttag.h> 


7.149.1 Detailed Description 


GtkTextA ppearance instance structure. 


The documentation for this struct was generated from the following file: 


e gtktexttag.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.150 _GtkTextAttributes Struct Reference 


#include <gtktexttag.h> 


7.150.1 Detailed Description 


GtkTextAttributes instance structure. 


The documentation for this struct was generated from the following file: 


e gtktexttag.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.151 _GtkTextBuffer Struct Reference 


#include <gtktextbuffer.h> 


7.151.1 Detailed Description 


GtkTextBuffer instance structure. 


The documentation for this struct was generated from the following file: 


e gtktextbuffer.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.152  _GtkTextBufferClass Struct Reference 


#include <gtktextbuffer.h> 


7.152.1 Detailed Description 


GtkTextBuffer instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktextbuffer.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.153 _GtkTextIter Struct Reference 


#include <gtktextiter.h> 


7.153.1 Detailed Description 


GtkTextIter instance structure. 


The documentation for this struct was generated from the following file: 


e gtktextiter.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.154 _GtkTextMark Struct Reference 
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7.154  _GtkTextMark Struct Reference 


#include <gtktextmark.h> 


7.154.1 Detailed Description 


GtkTextMark instance structure. 


The documentation for this struct was generated from the following file: 


e gtktextmark.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.155  _GtkTextMarkClass Struct Reference 


#include <gtktextmark.h> 


7.155.1 Detailed Description 


GtkTextMark instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktextmark.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.156 _GtkTextTag Struct Reference 


#include <gtktexttag.h> 


7.156.1 Detailed Description 


GtkTextTag instance structure. 


The documentation for this struct was generated from the following file: 


e gtktexttag.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


1002 Data Structure Documentation 


7.157 _GtkTextTagClass Struct Reference 


#include <gtktexttag.h> 


7.157.1 Detailed Description 


GtkTextTag instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktexttag.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.158 _GtkTextTagTable Struct Reference 


#include <gtktexttagtable.h> 


7.158.1 Detailed Description 


GtkTextTagTable instance structure. 


The documentation for this struct was generated from the following file: 


e gtktexttagtable.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.159 _GtkTextTagTableClass Struct Reference 


#include <gtktexttagtable.h> 


7.159.1 Detailed Description 


GtkTextTagTable instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktexttagtable.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.160 _GtkTextView Struct Reference 


#include <gtktextview.h> 


7.160.1 Detailed Description 


GtkTextView instance structure. 


Data Fields 


e guint text_max_length 


Max character. 


7.160.2 Field Documentation 
7.160.2.1 guint _GtkTextView::text_max_length 


Max character. 


The documentation for this struct was generated from the following file: 


e gtktextview.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.161 _GtkTextViewClass Struct Reference 


#include <gtktextview.h> 


7.161.1 Detailed Description 


GtkTextView instance class structure. 


Data Fields 


e void(* input_mode_changed )(GtkTextView *text_view, const gchar *input_method, const gchar 
*input_mode) 


IME notification call back function. 


7.161.2 Field Documentation 


7.161.2.1 void(« _GtkTextViewClass::input_mode_changed)(GtkTextView «text_view, const gchar 
xinput_method, const gchar +input_mode) 


IME notification call back function. 


Parameters: 
text_view [in] GtkTextView 
input_method [in] object name 


inputmode [in]IME current input mode 


The documentation for this struct was generated from the following file: 


e gtktextview.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.162 _GtkToggleButton Struct Reference 


#include <gtktogglebutton.h> 


7.162.1 Detailed Description 


GtkToggleButton interface structure. 


The documentation for this struct was generated from the following file: 


e gtktogglebutton.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


1008 Data Structure Documentation 


7.163 _GtkToggleButtonClass Struct Reference 


#include <gtktogglebutton.h> 


7.163.1 Detailed Description 


GtkToggleButton interface class structure. 


The documentation for this struct was generated from the following file: 


e gtktogglebutton.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.164 _GtkTreeModelFilter Struct Reference 


1009 


7.164  _GtkTreeModelFilter Struct Reference 


#include <gtktreemodelfilter.h> 


7.164.1 Detailed Description 


GtkTreeModelFilter instance structure. 


The documentation for this struct was generated from the following file: 


e gtktreemodelfilter.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.165  _GtkTreeModelFilterClass Struct Reference 


#include <gtktreemodelfilter.h> 


7.165.1 Detailed Description 


GtkTreeModelFilter instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktreemodelfilter.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


7.166 _GtkTreeModelSort Struct Reference 
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7.166 _GtkTreeModelSort Struct Reference 


#include <gtktreemodelsort.h> 


7.166.1 Detailed Description 


GtkTreeModelSort instance structure. 


The documentation for this struct was generated from the following file: 


e gtktreemodelsort.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.167 _GtkTreeModelSortClass Struct Reference 


#include <gtktreemodelsort.h> 


7.167.1 Detailed Description 


GtkTreeModelSort instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktreemodelsort.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.168 _GtkTreeSelection Struct Reference 


#include <gtktreeselection.h> 


7.168.1 Detailed Description 


GtkTreeSelection instance structure. 


The documentation for this struct was generated from the following file: 


e gtktreeselection.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.169 _GtkTreeSelectionClass Struct Reference 


#include <gtktreeselection.h> 


7.169.1 Detailed Description 


GtkTreeSelection instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktreeselection.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.170 _GtkTreeStore Struct Reference 


#include <gtktreestore.h> 


7.170.1 Detailed Description 


GtkTreeStore instance structure. 


The documentation for this struct was generated from the following file: 


e gtktreestore.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.171 _GtkTreeStoreClass Struct Reference 


#include <gtktreestore.h> 


7.171.1 Detailed Description 


GtkTreeStore instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktreestore.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.172 _GtkTreeView Struct Reference 


#include <gtktreeview.h> 


7.172.1 Detailed Description 


GtkTreeView instance structure. 


The documentation for this struct was generated from the following file: 


e gtktreeview.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.173 _GtkTreeViewClass Struct Reference 


#include <gtktreeview.h> 


7.173.1 Detailed Description 


GTK Native GtkTreeView instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktreeview.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.174 _GtkTreeViewColumn Struct Reference 


#include <gtktreeviewcolumn.h> 


7.174.1 Detailed Description 


GtkTree ViewColumn instance structure. 


The documentation for this struct was generated from the following file: 


e gtktreeviewcolumn.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.175 _GtkTreeViewColumnClass Struct Reference 


#include <gtktreeviewcolumn.h> 


7.175.1 Detailed Description 


GTK Native GtkTree ViewColumn instance class structure. 


The documentation for this struct was generated from the following file: 


e gtktreeviewcolumn.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.176 _GtkVBox Struct Reference 


#include <gtkvbox.h> 


7.176.1 Detailed Description 


GtkVBox instance structure. 


The documentation for this struct was generated from the following file: 


e gtkvbox.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.177 _GtkVBoxClass Struct Reference 


#include <gtkvbox.h> 


7.177.1 Detailed Description 


GtkVBox instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkvbox.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.178 _GtkViewport Struct Reference 


#include <gtkviewport.h> 


7.178.1 Detailed Description 


GtkViewport instance structure. 


The documentation for this struct was generated from the following file: 


e gtkviewport.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.179 _GtkViewportClass Struct Reference 


#include <gtkviewport.h> 


7.179.1 Detailed Description 


GtkViewport instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkviewport.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.180 —GtkVScale Struct Reference 


#include <gtkvscale.h> 


7.180.1 Detailed Description 


GtkVScale instance structure. 


The documentation for this struct was generated from the following file: 


e gtkvscale.h 
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7.181 _GtkVScaleClass Struct Reference 


#include <gtkvscale.h> 


7.181.1 Detailed Description 


GtkVScale instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkvscale.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.182 _GtkVScrollbar Struct Reference 


#include <gtkvscrollbar.h> 


7.182.1 Detailed Description 


GtkVScrollbar instance structure. 


The documentation for this struct was generated from the following file: 


e gtkvscrollbar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


1028 Data Structure Documentation 


7.183  _GtkVScrollbarClass Struct Reference 


#include <gtkvscrollbar.h> 


7.183.1 Detailed Description 


GtkVScrollbar instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkvscrollbar.h 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 
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7.184 _ GtkWidget Struct Reference 


#include <gtkwidget.h> 


7.184.1 Detailed Description 


The widget is the base of the tree for displayable objects. 


(A displayable object is one which takes up some amount of screen real estate). It provides a common base 


and interface which actual widgets must adhere to. 


Data Fields 


e GtkObject object 


The object structure needs to be the first element in the widget structure in order for the object mechanism 


to work correctly. 


e guintló private_flags 


16 bits of internally used private flags. 


e guint8 state 


The state of the widget. 


e guint8 saved_state 


The saved state of the widget. 


e gchar * name 


The widget’s name. 


e GtkStyle style 
The style for the widget. 


e GtkRequisition requisition 


The widget's desired size. 


e GtkAllocation allocation 


The widget's allocated size. 


e GdkWindow * window 


The widget’s window or its parent window if it does not have a window. 


e GtkWidget * parent 


The widget's parent. 


e guint bg_transparent:1 


whether to fill the widgets background 
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7.184.2 Field Documentation 
7.184.2.1 GtkObject _GtkWidget::object 


The object structure needs to be the first element in the widget structure in order for the object mechanism 
to work correctly. 


This allows a GtkWidget pointer to be cast to a GtkObject pointer. 


The documentation for this struct was generated from the following file: 


e gtkwidget.h 
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7.185  _GtkWindow Struct Reference 


#include <gtkwindow.h> 


7.185.1 Detailed Description 


Gtk Window instance structure. 


The documentation for this struct was generated from the following file: 


e gtkwindow.h 
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7.186 _GtkWindowClass Struct Reference 


#include <gtkwindow.h> 


7.186.1 Detailed Description 


GtkWindow instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkwindow.h 
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7.187 _GtkWindowGroup Struct Reference 


#include <gtkwindow.h> 


7.187.1 Detailed Description 


GtkWindowGroup instance structure. 


The documentation for this struct was generated from the following file: 


e gtkwindow.h 
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7.188 _GtkWindowGroupClass Struct Reference 


#include <gtkwindow.h> 


7.188.1 Detailed Description 


GtkWindowGroup instance class structure. 


The documentation for this struct was generated from the following file: 


e gtkwindow.h 
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Chapter 8 


File Documentation 


8.1 ComponentOverview.h File Reference 


8.1.1 Detailed Description 


Component Programming Interface Overview Header Template for Doxygen. 


This file contains configuration information for documentation generation; it does not contain any API- 
specific information. 


1036 File Documentation 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


Chapter 9 


Page Documentation 


9.1 New API List 


Global AppQuitStateHandler LIMO R1 
Global CMEventHandler LIMO R1 


Global gtk_main_set_app_quit_state_validator LIMO R1 


Global gtk_main_set_cm_event_handler LIMO R1 


Global gtk_settings_create_global_settings_object LIMO R1 


Global gtk_container_set_force_loop_focus LIMO R1 


Global gtk_container_set_in_focus LIMO R1 


Global gtk_widget_is_bg_ transparent LIMO R1 


Global gtk_widget_set_bg_transparent LIMO R1 


Global gtk_dialog_add_widget LIMO R1 


Global gtk_dialog_get_softkeybar LIMO R1 


Global gtk_dialog_get_title LIMO R1 
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Global gtk_dialog_get_width LIMO R1 


Global gtk_dialog_new_with_title LIMO R1 


Global gtk_dialog_set_softkeybar LIMO R1 


Global gtk_dialog_set_title LIMO R1 


Global gtk_dialog_set_width LIMO R1 


Global gtk_window_is_bg_transparent LIMO R1 


Global gtk_window_set_bg_transparent LIMO R1 


Global gtk_label_get_bold LIMO R1 


Global gtk_label_get_focusable LIMO R1 


Global gtk_label_get_slide_mode LIMO R1 


Global gtk_label_get_slide_pixel_interval LIMO R1 


Global gtk_label_get_slide_repeat_count LIMO R1 


Global gtk_label_get_slide_state LIMO R1 


Global gtk_label_get_time_out LIMO R1 


Global gtk_label_set_bold LIMO R1 


Global gtk_label_set_focusable LIMO R1 


Global gtk_label_set_slide_mode LIMO R1 


Global gtk_label_set_slide_pixel_interval LIMO R1 
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Global gtk_label_set_slide_repeat_count LIMO R1 


Global gtk_label_set_slide_state LIMO R1 


Global gtk_label_set_time_out LIMO R1 


Global gtk_entry_get_navigation_mode LIMO R1 


Global gtk_entry_get_prompt_string LIMO R1 


Global gtk_entry_get_remaining_input_byte_count LIMO R1 


Global gtk_entry_get_remaining_input_char_count LIMO R1 


Global gtk_entry_set_navigation_mode LIMO R1 


Global gtk_entry_set_prompt_string LIMO R1 


Global gtk_text_view_check_for_navigation LIMO R1 


Global gtk_text_view_get_byte_length LIMO R1 


Global gtk_text_view_get_max_byte_length LIMO R1 


Global gtk_text_view_get_max_char_length LIMO R1 


Global gtk_text_view_get_navigation_mode LIMO R1 


Global gtk_text_view_get_remaining_input_byte_count LIMO R1 


Global gtk_text_view_get_remaining_input_char_count LIMO R1 


Global gtk_text_view_get_visibility LIMO R1 


Global gtk_text_view_set_max_byte_length LIMO R1 
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Global gtk_text_view_set_max_char_length LIMO R1 


Global gtk_text_view_set_navigation_mode LIMO R1 


Global gtk_text_view_set_visibility LIMO R1 


Global gtk_tree_path_new_last LIMO R1 


Global gtk_tree_view_clear_all_item LIMO R1 


Global gtk_tree_view_set_tree_zoom_flag LIMO R1 


Global gtk_tree_view_set_zoom_line_height LIMO R1 


Global gtk_icon_view_get_icon_height LIMO R1 


Global gtk_cell_layout_pack_next_line LIMO R1 


Global gtk_cell_layout_pack_next_line_start LIMO R1 


Global gtk_cell_renderer_set_cell_flag LIMO R1 


Global gtk_cell_renderer_set_cell_font_size LIMO R1 


Global gtk_cell_renderer_set_render_scale LIMO R1 


Global gtk_cell_renderer_pixbuf_get_is_scale LIMO R1 


Global gtk_cell_renderer_pixbuf_get_scale_sb LIMO R1 


Global gtk_cell_renderer_pixbuf_set_is_scale LIMO R1 


Global gtk_cell_renderer_pixbuf_set_scale_sb LIMO R1 


Global gtk_cell_renderer_text_create_layout LIMO R1 
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Global gtk_cell_renderer_text_get_is_slider LIMO R1 


Global gtk_cell_renderer_text_set_slider LIMO R1 


Global gtk_menu_get_attach_softkey_position LIMO R1 


Global gtk_menu_set_attach_softkey_position LIMO R1 


Global gtk_menu_item_get_index LIMO R1 


Global gtk_notebook_append_page_with_tab_image LIMO R1 


Global gtk_notebook_get_tab_image LIMO R1 


Global gtk_notebook_get_tab_style LIMO R1 


Global gtk_notebook_insert_page_with_tab_image LIMO R1 


Global gtk_notebook_new_with_tab_style LIMO R1 


Global gtk_notebook_prepend_page_with_tab_image LIMO R1 


Global gtk_notebook_set_tab_image LIMO R1 


Global gtk_notebook_set_tab_style LIMO R1 


Global gtk_color_chooser_add LIMO R1 


Global gtk_color_chooser_color_from_string LIMO R1 


Global gtk_color_chooser_color_to_string LIMO R1 


Global gtk_color_chooser_convert_color_hue LIMO R1 


Global gtk_color_chooser_convert_color_saturation LIMO R1 
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Global gtk_color_chooser_convert_color_value LIMO R1 


Global gtk_color_chooser_extraction_color_hue LIMO R1 


Global gtk_color_chooser_extraction_color_saturation LIMO R1 


Global gtk_color_chooser_extraction_color_value LIMO R1 


Global gtk_color_chooser_get LIMO R1 


Global gtk_color_chooser_get_color_index LIMO R1 


Global gtk_color_chooser_get_count LIMO R1 


Global gtk_color_chooser_get_selection LIMO R1 


Global gtk_color_chooser_get_selection_index LIMO R1 


Global gtk_color_chooser_get_type LIMO R1 


Global gtk_color_chooser_insert LIMO R1 


Global gtk_color_chooser_mix_color_hsv LIMO R1 


Global gtk_color_chooser_new LIMO R1 


Global gtk_color_chooser_remove LIMO R1 


Global gtk_color_chooser_remove_all LIMO R1 


Global gtk_color_chooser_set LIMO R1 


Global gtk_color_chooser_set_selection_index LIMO R1 


Global gtk_focus_bin_get_focusable LIMO R1 
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Global gtk_focus_bin_get_inner_border LIMO R1 


Global gtk_focus_bin_get title LIMO R1 


Global gtk_focus_bin_get type LIMOR1 


Global gtk_focus_bin_new LIMO R1 


Global gtk_focus_bin_set_focusable LIMO R1 


Global gtk_focus_bin_set_inner_border LIMO R1 


Global gtk_focus_bin_set_title LIMO R1 


Global gtk_form_add_softkey LIMO R1 


Global gtk_form_construct LIMO R1 


Global gtk_form_get_has_softkey LIMO R1 


Global gtk_form_get_icon LIMO R1 


Global gtk_form_get_softkey_bar LIMO R1 


Global gtk_form_get_title LIMO R1 


Global gtk_form_get_type LIMO RI 


Global gtk_form_new LIMO R1 


Global gtk_form_set_has_softkey LIMO R1 


Global gtk_form_set_icon LIMO R1 


Global gtk_form_set_title LIMO R1 
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Global gtk_formatted_entry_get_alignment LIMO R1 


Global gtk_formatted_entry_get_inner_border LIMO R1 


Global gtk_formatted_entry_get_ip LIMO R1 


Global gtk_formatted_entry_get_style LIMO R1 


Global gtk_formatted_entry_get_time LIMO R1 


Global gtk_formatted_entry_get_tm LIMO R1 


Global gtk_formatted_entry_get_type LIMO R1 


Global gtk_formatted_entry_new LIMO R1 


Global gtk_formatted_entry_set_alignment LIMO R1 


Global gtk_formatted_entry_set_inner_border LIMO R1 


Global gtk_formatted_entry_set_ip LIMO R1 


Global gtk_formatted_entry_set_ip_with_text LIMO R1 


Global gtk_formatted_entry_set_style LIMO R1 


Global gtk_formatted_entry_set_time LIMO R1 


Global gtk_formatted_entry_set_tm LIMO R1 


Global gtk_indicator_construct LIMO R1 


Global gtk_indicator_display_clock LIMO R1 


Global gtk_indicator_get_data LIMO R1 
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Global gtk_indicator_new LIMO R1 


Global gtk_indicator_put_icon LIMO R1 


Global gtk_indicator_set_data LIMO R1 


Global gtk_indicator_show LIMO R1 


Global gtk_indicator_show_all LIMO R1 


Global gtk_main_window_add_form LIMO R1 


Global gtk_main_window_change_style LIMO R1 


Global gtk_main_window_construct LIMO R1 


Global gtk_main_window_get_current_form LIMO R1 


Global gtk_main_window_get_default_icon LIMO R1 


Global gtk_main_window_get_default_title LIMO R1 


Global gtk_main_window_get_form_number LIMO R1 


Global gtk_main_window_new LIMO R1 


Global gtk_main_window_new_with_screen LIMO R1 


Global gtk_main_window_remove_all_forms LIMO R1 


Global gtk_main_window_remove_current_form LIMO R1 


Global gtk_main_window_remove_form LIMO R1 


Global gtk_main_window_set_current_form LIMO R1 
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Global gtk_main_window_set_current_form_with_index LIMO R1 


Global gtk_main_window_set_default_icon LIMO R1 


Global gtk_main_window_set_default_ title LIMO R1 


Global gtk_main_window_set_indicator LIMO R1 


Global gtk_main_window_set_title_slide_time_out LIMO R1 


Global gtk_message_dialog_get type LIMO RI 


Global gtk_message_dialog_new LIMO R1 


Global gtk_message_dialog_set_destroy_timeout LIMO R1 


Global gtk_message_dialog_set_image LIMO R1 


Global gtk_simple_list_append LIMO R1 


Global gtk_simple_list_clear LIMO R1 


Global gtk_simple_list_get_style LIMO R1 


Global gtk_simple_list_get_type LIMO R1 


Global gtk_simple_list_insert LIMO R1 


Global gtk_simple_list_is_item_selected LIMO R1 


Global gtk_simple_list_new LIMO R1 


Global gtk_simple_list_prepend LIMO R1 


Global gtk_simple_list remove LIMO R1 
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Global gtk_simple_list_select_all LIMO R1 


Global gtk_simple_list_set_item_selected LIMO R1 


Global gtk_simple_list_set_style LIMO R1 


Global gtk_simple_list_unselect_all LIMO R1 


Global gtk_softkey_bar_get_keycode LIMO R1 


Global gtk_softkey_bar_get_softkey LIMO R1 


Global gtk_softkey_bar_get_softkey_number LIMO R1 


Global gtk_softkey_bar_new LIMO R1 


Global gtk_softkey_bar_reset_softkey LIMO R1 


Global gtk_softkey_bar_reset_softkey_all LIMO R1 


Global gtk_softkey_bar_set_softkey LIMO R1 


Global gtk_spin_add LIMO R1 


Global gtk_spin_get LIMO R1 


Global gtk_spin_get_count LIMO R1 


Global gtk_spin_get_selection LIMO R1 


Global gtk_spin_get_selection_index LIMO R1 


Global gtk_spin_get_type LIMO R1 


Global gtk_spin_insert LIMO R1 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


1048 Page Documentation 


Global gtk_spin_new LIMO R1 


Global gtk_spin_remove LIMO R1 


Global gtk_spin_remove_all LIMO R1 


Global gtk_spin_set LIMO R1 


Global gtk_spin_set_selection_index LIMO R1 


Global gtk_spin_set_wrap LIMO R1 


Global gtk_symbol_dialog_get_text LIMO R1 


Global gtk_symbol_dialog_get_type LIMO R1 


Global gtk_symbol_dialog new LIMO R1 


Global gtk_symbol_dialog_set_symbol LIMO R1 


Global gdk_window_enable_wm_redirection LIMO R1 


Global gtk_im_context_get_module_property LIMO R1 


Global gtk_im_context_get_module_property_list LIMO R1 


Global gtk_im_context_set_module_property LIMO R1 


Global gtk_im_multi_context_activate_im LIMO R1 


Global gtk_im_multi_context_get_activate_im LIMO R1 


Global gtk_im_multicontext_get_singleton_instance LIMO R1 


Global gtk_im_context_multitab_new LIMO R1 


Global im_module_exit LIMO R1 


Global im_module_init LIMO R1 


Global im_module_list LIMO R1 
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9.2 Modified Widget List 


Group GtkContainer LIMO R1 

Group GtkWidget LIMO R1 

Group GtkDialog LIMO R1 

Group GtkLabel LIMO R1 

Group GtkEntry LIMO R1 

Group GtkTextView LIMO R1 

Group GtkTreeViewColumn LIMO R1 
Group GtkTreeview LIMO R1 

Group GtkIconView LIMO R1 


Group GtkCellRenderer LIMO R1 


Group GtkCellRendererPixbuf LIMO R1 


Group GtkMenu LIMO R1 


Group GtkMenultem LIMO RI 


Group GtkMenuShell LIMO R1 


Group GtkCheckMenultem LIMO R1 


Group GtkRadioMenultem LIMO R1 


Group GtkNoteBook LIMO R1 


Group GdkWindow LIMO R1 


Group GtkIMContext LIMO R1 


Group GtkIMMultiContext LIMO R1 
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Global gtk_widget_add_mnemonic_label LIMO R1 
Global gtk_widget_list_mnemonic_labels LIMO R1 
Global gtk_widget_mnemonic_activate LIMO R1 


Global gtk_widget_remove_mnemonic_label LIMO R1 


Global gtk_dialog_get_has_separator LIMO R1 


Global gtk_dialog_set_has_separator LIMO R1 


Global gtk_window_add_mnemonic LIMO R1 


Global gtk_window_begin_move_drag LIMO R1 


Global gtk_window_begin_resize_drag LIMO R1 


Global gtk_window_deiconify LIMO R1 


Global gtk_window_get_mnemonic_modifier LIMO R1 


Global gtk_window_iconify LIMO R1 


Global gtk_window_mnemonic_activate LIMO R1 


Global gtk_window_remove_mnemonic LIMO R1 


Global gtk_window_set_mnemonic_modifier LIMO R1 


Global gtk_label_get_mnemonic_keyval LIMO R1 


Global gtk_label_get_mnemonic_widget LIMO R1 
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Global gtk_label_new_with_mnemonic LIMO R1 


Global gtk_label_set_markup_with_mnemonic LIMO R1 


Global gtk_label_set_mnemonic_widget LIMO R1 


Global gtk_label_set_text_with_mnemonic LIMO R1 


Global gtk_button_new_with_mnemonic LIMO R1 


Global gtk_check_button_new_with_mnemonic LIMO R1 


Global gtk_radio_button_new_with_mnemonic LIMO R1 


Global gtk_radio_button_new_with_mnemonic_from_widget LIMO R1 


Global gtk_toggle_button_new_with_mnemonic LIMO R1 


Global gtk_tree_view_create_row_drag_icon LIMO R1 


Global gtk_tree_view_enable_model_drag_dest LIMO R1 


Global gtk_tree_view_enable_model_drag_source LIMO R1 


Global gtk_tree_view_get_dest_row_at_pos LIMOR1 


Global gtk_tree_view_get_drag_dest_row LIMO R1 


Global gtk_tree_view_get_headers_clickable LIMO R1 


Global gtk_tree_view_set_column_drag function LIMO R1 


Global gtk_tree_view_set_drag_dest_row LIMO R1 


Global gtk_tree_view_set_headers_clickable LIMO R1 
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Global gtk 


tree 


view_unset_rows_drag_dest LIMO R1 


Global gtk 


tree 


view_unset_rows_drag_source LIMO R1 


Global gtk 


icon 


view_create_drag_icon LIMO R1 


Global gtk 


icon 


view_enable_model_drag dest LIMO R1 


Global gtk 


icon 


view_enable_model_drag_source LIMO R1 


icon 


Global gtk 


Global gtk 


icon 


view_get_dest_item_at_pos LIMO R1 


view_get_drag_dest_item LIMO R1 


Global gtk_icon_view_get_reorderable LIMO R1 


Global gtk_icon_view_set_drag_dest_item LIMO R1 


Global gtk_icon_view_set_reorderable LIMO R1 


Global gtk 


icon 


view_unset_model_drag_dest LIMO R1 


Global gtk 


icon 


view_unset_model_drag_source LIMO R1 


Global gtk 


menu_item_new_with_mnemonic LIMO R1 


Global gtk 


menu_item_set_accel_path LIMO R1 


Global gtk 


menu_item_set_right_justified LIMO R1 


Global gtk 


check_menu_item_get_draw_as_radio LIMO R1 


Global gtk 


check_menu_item_get_inconsistent LIMO R1 


Global gtk 


check_menu_item_new_with_mnemonic LIMO R1 
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Global gtk_check_menu_item_set_draw_as_radio LIMO R1 


Global gtk_check_menu_item_set_inconsistent LIMO R1 


Global gtk_radio_menu_item_new_with_mnemonic LIMO R1 


Global gtk_radio_menu_item_new_with_mnemonic_from_widget LIMO R1 


Global gtk_notebook_get_group_id LIMO R1 


Global gtk_notebook_popup_disable LIMO R1 


Global gtk_notebook_popup_enable LIMO R1 


Global gtk_notebook_set_group_id LIMO R1 
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Global gtk_menu_popdown LIMO R1 


Global gtk_menu_popup LIMO R1 


Global gtk_menu_reposition LIMO R1 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


9.5 New Class List 


1055 


9.5 New Class List 


Group GtkColorChooser LIMO R1 


Group GtkFocusBin LIMO R1 


Group GtkForm LIMO R1 


Group GtkFormattedEntry LIMO R1 


Group GtkIndicator LIMO R1 


Group GtkMainWindow LIMO RI 


Group GtkMessageDialog LIMO R1 


Group GtkSimpleList LIMO R1 


Group GtkSoftkeyBar LIMO R1 


Group GtkSpin LIMO R1 


Group GtkSymbolDialog LIMO R1 


Group GtkIMContextMultitab LIMO R1 
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_GtkCellRendererClass, 856 _GtkEntryClass, 886 
editing canceled, 856 activate, 886 
editing started, 856 copy_clipboard, 886 
_GtkCellRendererPixbuf, 858 cut_clipboard, 886 
_GtkCellRendererPixbufClass, 859 input_mode_changed, 887 
_GtkCellRendererProgress, 860 paste_clipboard, 886 
_GtkCellRendererProgressClass, 861 populate_popup, 887 
_GtkCellRendererText, 862 toggle_overwrite, 887 
_GtkCellRendererTextClass, 863 _GtkEntryCompletion, 888 
_GtkCellRendererToggle, 864 _GtkEntryCompletionClass, 889 
_GtkCellRendererToggleClass, 865 action_activated, 889 
toggled, 865 insert_prefix, 890 
_GtkCell View, 866 match_selected, 889 
_GtkCellViewClass, 867 _GtkEventBox, 891 
_GtkCheckButton, 868 _GtkEventBoxClass, 892 
_GtkCheckButtonClass, 869 _GtkFixed, 893 
_GtkCheckMenultem, 870 _GtkFixedClass, 894 
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